@openlup/platform 0.21.0 → 0.23.0

package/src/subscriptions/postgresRenewalStore.ts

@@ -0,0 +1,76 @@
+import type { RenewalDue, RenewalFrozenSnapshot, RenewalReadback, RenewalSchedule, RenewalStorePort } from "./contracts/renewal.js";
+
+/** Transaction-bound executors may be supplied; no driver, environment or account is selected here. */
+export interface SubscriptionQueryExecutor {
+  query(text: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+}
+/** The host preserves its native wire snapshot, identity dialect and evidence-bound numbering. */
+export interface NativeRenewalCodec {
+  due(row: Record<string, unknown>): RenewalDue;
+  freeze(row: Record<string, unknown>, schedule: RenewalSchedule): RenewalFrozenSnapshot;
+  encode(snapshot: RenewalFrozenSnapshot): Record<string, unknown>;
+  decode(snapshot: Record<string, unknown>): RenewalFrozenSnapshot;
+  readback(row: Record<string, unknown>): RenewalReadback;
+  identity(snapshot: RenewalFrozenSnapshot): string;
+  fingerprint(snapshot: RenewalFrozenSnapshot): string;
+}
+const SNAPSHOT_SQL = `SELECT s.id AS subscription_id,s.client_id,s.next_cycle_at::text AS scheduled_at,t.*,
+ COALESCE((SELECT jsonb_agg(jsonb_build_object('lineOrdinal',l.line_ordinal,'sku',l.sku,'quantity',l.quantity,
+ 'unitAmountMinor',l.unit_amount_minor) ORDER BY l.line_ordinal) FROM public.subscription_renewal_term_lines l
+ WHERE l.subscription_id=s.id),'[]'::jsonb) AS lines
+ FROM public.subscriptions s JOIN public.subscription_renewal_terms t ON t.subscription_id=s.id
+ WHERE s.id=$1::uuid AND s.next_cycle_at=$2::timestamptz`;
+export function subscriptionRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("subscription_renewal_response_invalid");
+  return value as Record<string, unknown>;
+}
+/** Native claim/prepare remain their original SQL transaction units. G23 is composed by the host. */
+export function createPostgresRenewalStore(executor: SubscriptionQueryExecutor, codec: NativeRenewalCodec): RenewalStorePort {
+  async function header(input: RenewalSchedule) {
+    const result = await executor.query(SNAPSHOT_SQL, [input.subscriptionId, input.scheduledAt]);
+    if (!result.rows[0]) throw new Error("subscription_renewal_snapshot_not_found");
+    return result.rows[0];
+  }
+  async function response(sql: string, values: unknown[]) {
+    return codec.readback(subscriptionRecord((await executor.query(sql, values)).rows[0]?.response));
+  }
+  return {
+    transactions: { graph: "native", prepare: "cycle_order_items_settlement_reservation_attempt",
+      outcome: "settlement_outcome_schedule_counter_reservation", recovery: "settlement_cycle_receipt_case_counter" },
+    async listDue(limit, asOf) {
+      const result = await executor.query(`SELECT due.*,due.scheduled_at::text AS scheduled_at
+        FROM public.subscription_list_due_renewals($1::timestamptz,$2::integer) due`, [asOf, limit]);
+      return result.rows.map(row => codec.due(row));
+    },
+    async buildCycleSnapshots(input) {
+      const stored = await executor.query(`SELECT cycle_snapshot FROM public.subscription_renewal_operations
+        WHERE subscription_id=$1::uuid AND scheduled_at=$2::timestamptz`, [input.subscriptionId, input.scheduledAt]);
+      return stored.rows[0] ? codec.decode(subscriptionRecord(stored.rows[0].cycle_snapshot)) : codec.freeze(await header(input), input);
+    },
+    async readMandateEvidence(input) {
+      const row = await header(input);
+      return { authorized: true, authorizationRef: String(row.authorization_ref),
+        authorizedAt: row.unattended_charge_authorized_at instanceof Date
+          ? row.unattended_charge_authorized_at.toISOString() : String(row.unattended_charge_authorized_at) };
+    },
+    async admitDeliveryAlignment(input) {
+      const row = await header(input);
+      if (row.delivery_admission !== "allowed" && row.delivery_admission !== "blocked") throw new Error("subscription_renewal_delivery_admission_invalid");
+      return row.delivery_admission === "allowed"
+        ? { allowed: true, state: "static", reason: "allowed" }
+        : { allowed: false, state: "static", reason: String(row.delivery_block_reason ?? "delivery_alignment_blocked"), deferred: false };
+    },
+    async claimDue(input) {
+      return response(`SELECT public.subscription_claim_due_renewal($1::text,$2::text,$3::jsonb,$4::text,$5::integer,$6::timestamptz) AS response`,
+        [codec.identity(input.snapshot), codec.fingerprint(input.snapshot), JSON.stringify(codec.encode(input.snapshot)), input.workerId, input.leaseSeconds ?? 300, input.now]);
+    },
+    async readRenewal(identityKey) {
+      const value = (await executor.query("SELECT public.subscription_read_renewal($1::text) AS response", [identityKey])).rows[0]?.response;
+      return value == null ? null : codec.readback(subscriptionRecord(value));
+    },
+    async refuseBeforePayment(input) {
+      return response("SELECT public.subscription_refuse_renewal_preflight($1::uuid,$2::uuid,$3::text,$4::timestamptz) AS response",
+        [input.operationId, input.claimToken, input.reason, input.occurredAt]);
+    },
+  };
+}

package/src/subscriptions/postgresRetryStore.ts

@@ -0,0 +1,174 @@
+import type { RenewalRetryObligation } from "./contracts/dunning.js";
+import type { RenewalReadback } from "./contracts/renewal.js";
+import { subscriptionRecord, type SubscriptionQueryExecutor } from "./postgresRenewalStore.js";
+
+/** N1 accepts only verified M07 evidence; the host supplies logical-cycle correlation explicitly. */
+export interface NativeRetryFailure {
+  attemptSequence: number; logicalCycleNumber: number; occurredAt: string;
+  failureClass: string; reason: string; externalRef: string | null;
+  evidenceKey: string; firstRecordedAt: string;
+}
+export interface NativeRetryRequest {
+  paymentIntentId: string; orderRef: string; amountMinor: number; currency: string;
+  idempotencyKey: string; providerIdempotencyKey: string; providerRequestFingerprint: string; paymentMethodRef: string;
+}
+export interface NativeRetryPositive {
+  prepareKey?: string; evidenceKey: string; occurredAt: string; firstRecordedAt: string;
+  externalRef: string; amountMinor: number; currency: string; template: string;
+}
+export interface NativeRetryPreparation {
+  execute: boolean; replayed: boolean; obligationId: string; attemptSequence: number;
+  cycleId: string; orderId: string; settlementIntentId: string; identityKey: string;
+  operationFingerprint: string; snapshot: Record<string, unknown>; request: NativeRetryRequest;
+}
+export interface NativeRetryRow extends RenewalRetryObligation {
+  caseId: string | null; state: "waiting" | "prepared" | "recovered";
+}
+/** No payment execution is implemented here. A replayed prepare always returns execute=false. */
+export function createPostgresRetryStore(executor: SubscriptionQueryExecutor) {
+  async function invoke(name: string, values: unknown[]) {
+    const result = await executor.query(`SELECT public.${name}(${values.map((_, i) => `$${i + 1}`).join(",")}) AS response`, values);
+    return result.rows[0]?.response;
+  }
+  function row(value: unknown): NativeRetryRow {
+    const r = subscriptionRecord(value), snapshot = subscriptionRecord(r.cycle_snapshot);
+    if (!["waiting", "prepared", "recovered"].includes(String(r.state))) throw new Error("subscription_retry_state_invalid");
+    return { operationId: String(r.renewal_operation_id), subscriptionId: String(r.subscription_id),
+      cycleId: String(r.cycle_id), orderId: String(r.order_id), settlementIntentId: String(r.settlement_intent_id),
+      logicalCycleNumber: Number(r.logical_cycle_number), nativeRenewalCounter: Number(snapshot.cycleNumber),
+      retryAttempt: Number(r.retry_attempt), externalAttemptSequence: Number(r.attempt_sequence),
+      nextRetryAt: r.next_retry_at == null ? null : String(r.next_retry_at),
+      failureClass: r.failure_class == null ? null : String(r.failure_class),
+      failureReason: r.failure_reason == null ? null : String(r.failure_reason), occurredAt: String(r.failed_at),
+      identityKey: String(r.identity_key), requestFingerprint: String(r.operation_fingerprint),
+      disposition: r.state === "recovered" ? "paid" : r.state === "prepared" || r.next_retry_at != null ? "retry_scheduled" : "payment_failed",
+      caseId: r.case_id == null ? null : String(r.case_id), state: r.state as NativeRetryRow["state"] };
+  }
+  return {
+    async read(operationId: string): Promise<NativeRetryRow | null> {
+      const value = await invoke("subscription_retry_read", [operationId]); return value == null ? null : row(value);
+    },
+    async candidates(limit: number, now: string): Promise<NativeRetryRow[]> {
+      const value = await invoke("subscription_retry_candidates", [limit, now]);
+      if (!Array.isArray(value)) throw new Error("subscription_retry_candidates_invalid");
+      return value.map(row);
+    },
+    async applyFailure(operationId: string, key: string, input: NativeRetryFailure) {
+      return row(await invoke("subscription_retry_apply_failure", [operationId, key, input]));
+    },
+    async openCase(operationId: string, template: string, recoveryPath: string | null) {
+      return subscriptionRecord(await invoke("subscription_retry_open_case", [operationId, template, recoveryPath]));
+    },
+    async authorizeRecovery(operationId: string, tokenId: string, methodRef: string, methodEvidenceRef: string, now: string) {
+      return subscriptionRecord(await invoke("subscription_retry_authorize_recovery", [operationId, tokenId, methodRef, methodEvidenceRef, now]));
+    },
+    async scheduleRecovery(operationId: string, key: string, authorizationId: string, now: string) {
+      return subscriptionRecord(await invoke("subscription_retry_schedule_recovery", [operationId, key, authorizationId, now]));
+    },
+    async prepare(operationId: string, key: string, input: NativeRetryRequest, now: string): Promise<NativeRetryPreparation> {
+      return subscriptionRecord(await invoke("subscription_retry_prepare", [operationId, key, input, now])) as unknown as NativeRetryPreparation;
+    },
+    async recordRecovery(operationId: string, key: string, input: NativeRetryPositive) {
+      return row(await invoke("subscription_retry_record_recovery", [operationId, key, input]));
+    },
+    async noteRowOutcome(operationId: string, key: string, input: Record<string, unknown>) {
+      return subscriptionRecord(await invoke("subscription_retry_note_row_outcome", [operationId, key, input]));
+    },
+  };
+}
+
+export interface NativeRetryLifecycleBinding {
+  executor: SubscriptionQueryExecutor;
+  withTransaction<T>(work: (executor: SubscriptionQueryExecutor) => Promise<T>): Promise<T>;
+  /** M07's existing transaction-bound native port; never a provider execution port. */
+  settlement(executor: SubscriptionQueryExecutor): import("./contracts/renewal.js").RenewalSettlementPort;
+  correlate(snapshot: Record<string, unknown>, nativeRenewalCounter: number): import("./contracts/renewal.js").RenewalCycleCorrelation;
+  failureTemplate: string;
+  recoveryPath: string | null;
+}
+/** Initial handoff opens only the existing donor-keyed case. Terminal outcome and
+ * N1 bookkeeping then commit together, so a crash cannot strand that schedule.
+ * Subsequent retry attempts use applyFailure/openCase separately, as before. */
+export function createPostgresRetryLifecycleBinding(options: NativeRetryLifecycleBinding): {
+  failureHandoff: import("./contracts/dunning.js").RenewalFailureHandoffPort;
+  settlement: import("./contracts/renewal.js").RenewalSettlementPort;
+} {
+  const base = options.settlement(options.executor);
+  return {
+    failureHandoff: {
+      async handoffFailure(input) {
+        const result = await options.executor.query(`SELECT public.dunning_lifecycle_open_case(
+          $1::text,$2::uuid,$3::uuid,$4::uuid,$5::integer,$6::timestamptz,$7::text,$8::text,
+          $9::timestamptz,$10::bigint,$11::text,$12::text,$13::text) AS response`,
+        [input.idempotencyKey, input.subscriptionId, input.cycleId, input.clientId, input.retryAttempt,
+          input.nextRetryAt, input.failureClass, input.failureReason, input.occurredAt, input.amountMinor,
+          input.currency, options.failureTemplate, options.recoveryPath]);
+        const row = subscriptionRecord(result.rows[0]?.response);
+        return { caseId: String(row.caseId), replayed: row.replayed === true };
+      },
+    },
+    settlement: {
+      prepareRenewal(input) { return base.prepareRenewal(input); },
+      acknowledgeExternalAttempt(input) { return base.acknowledgeExternalAttempt(input); },
+      async recordTerminalOutcome(input) {
+        if (input.outcome !== "refused") return base.recordTerminalOutcome(input);
+        return options.withTransaction(async executor => {
+          // Own subscription -> operation, the order used by the retry lifecycle.
+          await executor.query(`SELECT id FROM public.subscriptions WHERE id=(SELECT subscription_id
+            FROM public.subscription_renewal_operations WHERE id=$1::uuid) FOR UPDATE`, [input.operationId]);
+          const result = await executor.query(`SELECT op.cycle_snapshot,op.cycle_number,c.id AS case_id,
+            c.failure_class,c.failure_reason,c.next_retry_at::text AS next_retry_at,c.opened_at::text AS occurred_at,
+            receipt.input AS initial_failure,
+            public.subscription_renewal_operation_response(op,false,true,'terminal_replay') AS terminal_response,
+            terminal.id IS NOT NULL AND (terminal.reason IS DISTINCT FROM NULLIF(btrim($3::text),'')
+              OR terminal.occurred_at IS DISTINCT FROM $4::timestamptz
+              OR terminal.external_ref IS DISTINCT FROM $5::text
+              OR terminal.operation_fingerprint IS DISTINCT FROM $6::text
+              OR op.operation_fingerprint IS DISTINCT FROM $6::text
+              OR ($5::text IS NOT NULL AND op.external_attempt_ref IS DISTINCT FROM $5::text)
+              OR terminal.outcome <> 'refused') AS conflicting_terminal
+            FROM public.subscription_renewal_operations op
+            JOIN public.subscription_cycles cycle ON cycle.renewal_operation_id=op.id
+            JOIN public.subscription_dunning_cases c ON c.cycle_id=cycle.id
+              AND c.idempotency_key=op.identity_key||':failure-handoff'
+            LEFT JOIN public.subscription_retry_obligations obligation ON obligation.renewal_operation_id=op.id
+            LEFT JOIN public.subscription_retry_receipts receipt ON receipt.obligation_id=obligation.id
+              AND receipt.receipt_key=$2::text AND receipt.kind='failure' AND receipt.attempt_sequence=0
+            LEFT JOIN public.subscription_renewal_outcomes terminal ON terminal.renewal_operation_id=op.id
+              AND terminal.event_key=$2::text
+            WHERE op.id=$1::uuid`, [input.operationId, input.eventKey, input.reason ?? null, input.occurredAt,
+              input.externalRef ?? null, input.operationFingerprint]);
+          const handoff = result.rows[0];
+          // Provider-input preflight refusals never opened a customer case.
+          if (!handoff) return options.settlement(executor).recordTerminalOutcome(input);
+          if (handoff.conflicting_terminal) throw new Error("subscription_retry_replay_conflict");
+          // The immutable receipt ends replay before any settlement, rebinding
+          // or case propagation. The projection may describe a later attempt.
+          if (handoff.initial_failure != null) {
+            return subscriptionRecord(handoff.terminal_response) as unknown as RenewalReadback;
+          }
+          const correlation = options.correlate(subscriptionRecord(handoff.cycle_snapshot), Number(handoff.cycle_number));
+          if (correlation.status !== "correlated") throw new Error("subscription_renewal_cycle_correlation_required");
+          const recorded = await options.settlement(executor).recordTerminalOutcome(input);
+          const retry = createPostgresRetryStore(executor);
+          await retry.applyFailure(input.operationId, input.eventKey, {
+            attemptSequence: 0, logicalCycleNumber: correlation.logicalCycleNumber,
+            occurredAt: String(handoff.occurred_at),
+            failureClass: String(handoff.failure_class),
+            reason: String(handoff.failure_reason), externalRef: input.externalRef ?? null,
+            evidenceKey: input.eventKey, firstRecordedAt: String(handoff.occurred_at),
+          });
+          // The original handoff owns cadence, including a deliberate null.
+          const linked = await executor.query(`UPDATE public.subscription_retry_obligations SET case_id=$2::uuid,
+            next_retry_at=CASE WHEN attempt_sequence=0 AND retry_attempt=1 AND state='waiting'
+              THEN $3::timestamptz ELSE next_retry_at END
+            WHERE renewal_operation_id=$1::uuid AND (case_id IS NULL OR case_id=$2::uuid) RETURNING case_id`,
+          [input.operationId, handoff.case_id, handoff.next_retry_at]);
+          if (linked.rows.length !== 1) throw new Error("subscription_retry_initial_case_conflict");
+          await retry.openCase(input.operationId, options.failureTemplate, options.recoveryPath);
+          return recorded;
+        });
+      },
+    },
+  };
+}

package/src/subscriptions/renewalCycleFailureMechanism.ts

@@ -0,0 +1,119 @@
+import { nextRetryAttemptAt } from "@openlup/core/subscription";
+import type {
+  CycleChargeFailurePropagationPort, FailurePropagationContext, FailurePropagationResult,
+  CycleRetryState,
+} from "./contracts/renewal.js";
+
+export interface RenewalFailurePolicy {
+  resolveClassification(supplied: FailurePropagationContext["failureClassification"], reason: string): { failureClass: string; decidedBy: string };
+  recordKey(key: string): string;
+  applyKey(key: string): string;
+  dunningKey(key: string, attempt: number): string;
+  preparedSuffix: string;
+  blockedSuffix: string;
+  dunningFailureKey: string;
+  logBelowRetry(fields: { cycleId: string; retryAttempt: number }): void;
+  logRejected(fields: { cycleId: string; subscriptionId: string; retryAttempt: number; rowOutcomeKey: string; code?: string; reason: string }): void;
+  logUnavailable(fields: { cycleId: string; subscriptionId: string; retryAttempt: number; rowOutcomeKey: string; reason: string }): void;
+}
+
+/** Complete durable refusal ladder; unexpected port throws remain raw. */
+export async function propagateRenewalFailure(
+  port: CycleChargeFailurePropagationPort,
+  ctx: FailurePropagationContext,
+  policy: RenewalFailurePolicy,
+): Promise<FailurePropagationResult> {
+  if (ctx.kind === "off_session_requires_action" && ctx.attemptAlreadyPrepared !== true) {
+    return { dunningCaseId: null, retryAttempt: null, applyReplayed: false, dunningPropagationFailed: false };
+  }
+  if (ctx.kind === "preflight_block" && ctx.attemptAlreadyPrepared !== true) {
+    await port.recordBlockedPreflightAttempt({
+      idempotencyKey: policy.recordKey(ctx.executionIdempotencyKey),
+      paymentIntentId: ctx.paymentIntentId,
+      providerKind: ctx.providerKind,
+      providerIdempotencyKey: ctx.providerIdempotencyKey,
+      providerRequestFingerprint: ctx.providerRequestFingerprint,
+      failureReason: ctx.failureReason,
+    });
+  }
+  // A replay fingerprints the first durable instant, with caller time only as fallback.
+  const occurredAt = await resolveDurableOccurredAt(port, ctx, policy);
+  const applied = await port.applyFailedResult({
+    idempotencyKey: policy.applyKey(ctx.executionIdempotencyKey),
+    paymentIntentId: ctx.paymentIntentId,
+    occurredAt,
+    failureReason: ctx.failureReason,
+    failureClassification: policy.resolveClassification(ctx.failureClassification, ctx.failureReason),
+  });
+  const cycleSnapshot = await port.readCycleRetryState(ctx.cycleId);
+  return {
+    ...await openDunningCase(port, ctx, cycleSnapshot, occurredAt, policy),
+    applyReplayed: applied.replayed,
+  };
+}
+async function resolveDurableOccurredAt(
+  port: Pick<CycleChargeFailurePropagationPort, "readDurableAttemptInstant">,
+  ctx: FailurePropagationContext,
+  policy: RenewalFailurePolicy,
+): Promise<string> {
+  const suffix = ctx.attemptAlreadyPrepared === true ? policy.preparedSuffix : policy.blockedSuffix;
+  const durable = await port.readDurableAttemptInstant({
+    paymentIntentId: ctx.paymentIntentId,
+    attemptIdempotencyKey: `${ctx.executionIdempotencyKey}${suffix}`,
+  });
+  return durable !== null && durable.length > 0 ? durable : ctx.occurredAt;
+}
+async function openDunningCase(
+  port: Pick<CycleChargeFailurePropagationPort, "openDunningCase">,
+  ctx: FailurePropagationContext,
+  cycle: CycleRetryState,
+  occurredAt: string,
+  policy: RenewalFailurePolicy,
+): Promise<Omit<FailurePropagationResult, "applyReplayed">> {
+  const retryAttempt = cycle.retryAttempt ?? 1;
+  // Resolve again after the retry read: original context evidence remains dynamic.
+  const failureClass = policy.resolveClassification(
+    ctx.failureClassification,
+    ctx.failureReason,
+  ).failureClass;
+  const stranded = { cycleId: ctx.cycleId, subscriptionId: ctx.subscriptionId, retryAttempt,
+    rowOutcomeKey: policy.dunningFailureKey };
+  if (retryAttempt < 1) {
+    policy.logBelowRetry({ cycleId: ctx.cycleId, retryAttempt });
+    return { dunningCaseId: null, retryAttempt, dunningPropagationFailed: false };
+  }
+  // A stored null is a deliberate no-retry decision, not a missing row.
+  const nextRetryAt = cycle.rowPresent
+    ? cycle.nextRetryAt
+    : nextRetryAttemptAt(
+      occurredAt,
+      retryAttempt,
+      undefined,
+      failureClass,
+    );
+  const outcome = await port.openDunningCase({
+    idempotencyKey: policy.dunningKey(ctx.executionIdempotencyKey, retryAttempt),
+    cycleId: ctx.cycleId,
+    subscriptionId: ctx.subscriptionId,
+    orderUuid: ctx.orderUuid,
+    paymentIntentId: ctx.paymentIntentId,
+    retryAttempt,
+    nextRetryAt,
+    failureReason: ctx.failureReason,
+    occurredAt,
+    failureClass,
+  });
+  if (outcome.status === "rejected") {
+    policy.logRejected({
+      ...stranded, code: outcome.code, reason: outcome.reason,
+    });
+    return { dunningCaseId: null, retryAttempt, dunningPropagationFailed: true };
+  }
+  if (outcome.status === "unavailable") {
+    policy.logUnavailable({
+      ...stranded, reason: outcome.reason,
+    });
+    return { dunningCaseId: null, retryAttempt, dunningPropagationFailed: true };
+  }
+  return { dunningCaseId: outcome.caseId, retryAttempt, dunningPropagationFailed: false };
+}

package/src/subscriptions/renewalCycleMechanism.ts

@@ -0,0 +1,225 @@
+import type {
+  PaymentExecutionBaseInput, PaymentExecutionBaseResult, PaymentProviderCapabilityDescriptor,
+  ProviderAttemptIdentity,
+} from "@openlup/core/payment";
+import type { RenewalPreparedAttemptPersistencePort } from "./contracts/renewal.js";
+import type {
+  HostedRenewalDue, SubscriptionRenewalChargeResult, SubscriptionCycleSnapshotResult,
+  SubscriptionCycleOrderResult, RenewalIntentResult, RenewalCycleDeps,
+  RenewalExecutionContext, RenewalPrepareInput, RenewalAttemptResult,
+  RenewalDeliveryClient, RenewalAllowedAdmission, RenewalDeliveryAdmission,
+} from "./contracts/renewal.js";
+import {
+  recordRenewalPreflightBlock, replayRenewalAttempt, declinedRenewalOutcome, requiresActionRenewalOutcome,
+  type RenewalPreflightPolicy, type RenewalReplayPolicy, type RenewalOutcomePolicy,
+} from "./renewalCycleRefusalMechanism.js";
+
+export interface RenewalCyclePolicy<D extends HostedRenewalDue, CI, IR extends RenewalIntentResult,
+  P extends string, I extends PaymentExecutionBaseInput, M extends string | null | undefined, F extends string> {
+  validateProvider(due: D): string | null;
+  readTotal(snapshot: Record<string, unknown>): number | null;
+  failed(due: D, cycleId: string | null, cycleNumber: number | null, orderId: string | null, intentId: string | null, reason: string): SubscriptionRenewalChargeResult;
+  cycleKey(due: D): string;
+  executionKey(key: string, retry: number, sequence: number): string;
+  intentInput(due: D, key: string, snapshots: SubscriptionCycleSnapshotResult, order: SubscriptionCycleOrderResult, total: number): CI;
+  identity(due: D, key: string, intent: IR, order: SubscriptionCycleOrderResult, total: number): ProviderAttemptIdentity;
+  providerFlow(flow: string): F;
+  prepareInput(due: D, context: RenewalExecutionContext<IR, M, F>): RenewalPrepareInput<P>;
+  executionInput(due: D, context: RenewalExecutionContext<IR, M, F>, deps: { capability: PaymentProviderCapabilityDescriptor }): I;
+  isNotChargeable(error: unknown): boolean;
+  skippedNotChargeable(due: D, context: { cycleId: string; cycleNumber: number; orderId: string; paymentIntentId: string }): SubscriptionRenewalChargeResult;
+  finalizeKey(key: string): string;
+  executionIndeterminate(): Error;
+  defaultNow(): string;
+  mandateBlockReason: string;
+  invalidTotalsReason: string;
+  reservationBlockReason: string;
+  preflight: RenewalPreflightPolicy<D, CI, IR>;
+  replay: RenewalReplayPolicy;
+  outcome: RenewalOutcomePolicy;
+}
+
+/** One hosted cycle: admission and stock precede one prepare/execute/finalize. */
+export async function executeRenewalCycle<D extends HostedRenewalDue, CI, IR extends RenewalIntentResult,
+  P extends string, N extends string, I extends PaymentExecutionBaseInput,
+  R extends PaymentExecutionBaseResult & { nextActionKind: N | null },
+  M extends string | null | undefined, F extends string>(
+  deps: RenewalCycleDeps<CI, IR, P, N, I, R, M>, due: D,
+  policy: RenewalCyclePolicy<D, CI, IR, P, I, M, F>,
+): Promise<SubscriptionRenewalChargeResult> {
+  const deliveryBlock = deps.deliveryAlignmentAdmission ? null
+    : (await checkRenewalDeliveryAdmission(deps.deliveryAlignment, due, (deps.now ?? policy.defaultNow)())).blocked;
+  if (deliveryBlock) return deliveryBlock;
+  const providerValidation = policy.validateProvider(due);
+  if (providerValidation !== null) {
+    return recordRenewalPreflightBlock(deps, due, providerValidation, policy.preflight);
+  }
+  const paymentMethodRecurringModel = deps.capability.requiresStoredMandateEvidence
+    ? await deps.persistence.readMandateRecurringModel(due.providerKind, due.providerMethodRef) : undefined;
+  if (!deps.capability.assessMandate({ recurringModel: paymentMethodRecurringModel }).chargeable) {
+    return recordRenewalPreflightBlock(deps, due, policy.mandateBlockReason, policy.preflight);
+  }
+  const snapshots = await deps.persistence.buildCycleSnapshots({
+    subscriptionId: due.subscriptionId,
+    scheduledAt: due.nextCycleAt,
+  });
+  const totalGrossMinor = policy.readTotal(snapshots.orderSnapshot);
+  if (totalGrossMinor === null) {
+    return policy.failed(due, null, snapshots.cycleNumber, null, null, policy.invalidTotalsReason);
+  }
+  const cycleOrderIdempotencyKey = policy.cycleKey(due);
+  const cycleOrder = await deps.persistence.createCycleOrder({
+    idempotencyKey: cycleOrderIdempotencyKey,
+    subscriptionId: due.subscriptionId,
+    cycleNumber: snapshots.cycleNumber,
+    scheduledAt: due.nextCycleAt,
+    templateSnapshot: snapshots.templateSnapshot,
+    pricingSnapshot: snapshots.pricingSnapshot,
+    orderSnapshot: snapshots.orderSnapshot,
+  });
+  const reservationPreflight = await deps.persistence.preflightReservation({
+    orderId: cycleOrder.orderUuid,
+    now: (deps.now ?? policy.defaultNow)(),
+  });
+  if (!reservationPreflight.ok) {
+    return policy.failed(
+      due,
+      cycleOrder.cycleId,
+      snapshots.cycleNumber,
+      cycleOrder.orderUuid,
+      null,
+      reservationPreflight.reason ?? policy.reservationBlockReason,
+    );
+  }
+  const intent = await deps.paymentPort.createIntent(policy.intentInput(due, cycleOrderIdempotencyKey, snapshots, cycleOrder, totalGrossMinor));
+  const executionIdempotencyKey = policy.executionKey(
+    cycleOrderIdempotencyKey, snapshots.retryAttempt, snapshots.providerAttemptSequence,
+  );
+  const attemptIdentity = policy.identity(due, executionIdempotencyKey, intent, cycleOrder, totalGrossMinor);
+  const providerFlow = policy.providerFlow(deps.capability.unattendedChargeFlow);
+  const state = { snapshots, cycleOrder, intent, totalGrossMinor, executionIdempotencyKey,
+    attemptIdentity, providerFlow, paymentMethodRecurringModel };
+  const preparedAttempt = await prepareRenewalAttempt(deps.paymentPort,
+    policy.prepareInput(due, state), policy.isNotChargeable);
+  if (!preparedAttempt) {
+    return policy.skippedNotChargeable(due, {
+      cycleId: cycleOrder.cycleId,
+      cycleNumber: snapshots.cycleNumber,
+      orderId: cycleOrder.orderUuid,
+      paymentIntentId: intent.paymentIntentId,
+    });
+  }
+  if (preparedAttempt.replayed) {
+    return replayRenewalAttempt(
+      deps,
+      due,
+      {
+        cycleId: cycleOrder.cycleId,
+        cycleNumber: snapshots.cycleNumber,
+        orderId: cycleOrder.orderUuid,
+        paymentIntentId: intent.paymentIntentId,
+        executionIdempotencyKey,
+        providerIdempotencyKey: attemptIdentity.providerIdempotencyKey,
+        providerRequestFingerprint: attemptIdentity.providerRequestFingerprint,
+        providerKind: due.providerKind,
+      },
+      preparedAttempt.status, policy.replay,
+    );
+  }
+  // DTO construction and dispatch share the indeterminate execution boundary.
+  let execution: R;
+  try {
+    execution = await deps.executionPort.execute(policy.executionInput(due, state, deps));
+  } catch {
+    throw policy.executionIndeterminate();
+  }
+  // Finalization is one raw call outside that catch; it cannot authorize redispatch.
+  const finalizedAttempt = await deps.paymentPort.finalizeProviderAttempt({
+    idempotencyKey: policy.finalizeKey(executionIdempotencyKey),
+    paymentIntentId: intent.paymentIntentId,
+    paymentAttemptId: preparedAttempt.paymentAttemptId,
+    providerIdempotencyKey: attemptIdentity.providerIdempotencyKey,
+    providerRequestFingerprint: attemptIdentity.providerRequestFingerprint,
+    providerAttemptId: execution.providerAttemptId,
+    providerSessionId: execution.providerSessionId,
+    attemptStatus: execution.attemptStatus,
+    nextActionKind: execution.nextActionKind,
+    requestPayload: execution.requestPayload,
+    responsePayload: execution.responsePayload,
+  });
+  if (execution.providerDecline) {
+    return declinedRenewalOutcome(deps, due, {
+      decline: execution.providerDecline,
+      executionIdempotencyKey,
+      attemptIdentity,
+      intent,
+      cycleOrder,
+      snapshots,
+      finalizedAttempt,
+    }, policy.outcome);
+  }
+  if (execution.attemptStatus === "requires_action") {
+    return requiresActionRenewalOutcome(deps, due, {
+      executionIdempotencyKey,
+      attemptIdentity,
+      intent,
+      cycleOrder,
+      snapshots,
+      finalizedAttempt,
+    }, policy.outcome);
+  }
+  return {
+    subscriptionId: due.subscriptionId,
+    outcome: "charged",
+    cycleId: cycleOrder.cycleId,
+    cycleNumber: snapshots.cycleNumber,
+    orderId: cycleOrder.orderUuid,
+    paymentIntentId: intent.paymentIntentId,
+    attemptStatus: finalizedAttempt.status,
+    replayed: cycleOrder.replayed || intent.replayed,
+  };
+}
+
+export async function prepareRenewalAttempt<P extends string, N extends string>(
+  paymentPort: RenewalPreparedAttemptPersistencePort<P, N>, input: RenewalPrepareInput<P>,
+  isNotChargeable: (error: unknown) => boolean,
+): Promise<RenewalAttemptResult<N> | null> {
+  try {
+    return await paymentPort.prepareProviderAttempt(input);
+  } catch (error) {
+    if (isNotChargeable(error)) return null;
+    throw error;
+  }
+}
+
+export async function checkRenewalDeliveryAdmission(
+  client: RenewalDeliveryClient, due: Pick<HostedRenewalDue, "subscriptionId" | "nextCycleAt">, asOf: string,
+): Promise<{ admitted: RenewalAllowedAdmission; blocked: null } | { admitted: null; blocked: SubscriptionRenewalChargeResult }> {
+  const admission = await callRenewalDeliveryAdmission(client, {
+    subscriptionId: due.subscriptionId,
+    scheduledAt: due.nextCycleAt,
+    asOf,
+  });
+  if (admission.allowed) {
+    return { admitted: admission as RenewalAllowedAdmission, blocked: null };
+  }
+  return { admitted: null, blocked: {
+    subscriptionId: due.subscriptionId,
+    outcome: "skipped",
+    cycleId: null,
+    cycleNumber: null,
+    orderId: null,
+    paymentIntentId: null,
+    attemptStatus: null,
+    replayed: false,
+    reason: admission.reason,
+  } };
+}
+
+// Preserve the original admission call's async adoption before observing its result.
+async function callRenewalDeliveryAdmission(
+  client: RenewalDeliveryClient,
+  input: Parameters<RenewalDeliveryClient["admitDeliveryAlignment"]>[0],
+): Promise<RenewalDeliveryAdmission> {
+  return client.admitDeliveryAlignment(input);
+}