@openlup/platform 0.21.0 → 0.23.0

package/src/subscriptions/automaticRenewalExecution.ts

@@ -0,0 +1,39 @@
+import { nextRetryAttemptAt } from "@openlup/core/subscription";
+import type { RenewalDue, RenewalPaymentRail, RenewalReadback, RenewalSettlementPort, RenewalStorePort } from "./contracts/renewal.js";
+import type { AutomaticRenewalPolicy, AutomaticRenewalRunDeps, AutomaticRenewalRunResult, AutomaticRenewalRunStatus } from "./automaticRenewal.js";
+export function automaticRenewalResult(operation: RenewalReadback, status: AutomaticRenewalRunStatus, reason: string | null): AutomaticRenewalRunResult {
+  return { subscriptionId: operation.subscriptionId, identityKey: operation.identityKey, operationId: operation.operationId, status, replayed: operation.replayed, reason };
+}
+export async function recoverPreparedExternalAttempt(input: { operation: RenewalReadback; rail: RenewalPaymentRail; settlement: RenewalSettlementPort; occurredAt: string }): Promise<string | null> {
+  if (input.operation.externalAttemptRef) return input.operation.externalAttemptRef;
+  if (!input.operation.settlementIntentId) return null;
+  const externalAttemptRef = await input.rail.findExternalAttempt({ settlementIntentId: input.operation.settlementIntentId });
+  if (!externalAttemptRef) return null;
+  await input.settlement.acknowledgeExternalAttempt({ operationId: input.operation.operationId, operationFingerprint: input.operation.operationFingerprint, externalAttemptRef, acknowledgedAt: input.occurredAt });
+  return externalAttemptRef;
+}
+export async function runRenewalBatchRows(due: RenewalDue[], run: (row: RenewalDue) => Promise<AutomaticRenewalRunResult>, policy: Pick<AutomaticRenewalPolicy, "identityKey">): Promise<AutomaticRenewalRunResult[]> {
+  const results: AutomaticRenewalRunResult[] = [];
+  for (const row of due) {
+    try { results.push(await run(row)); }
+    catch { results.push({ subscriptionId: row.subscriptionId, identityKey: policy.identityKey(row), operationId: "", status: "error", replayed: false, reason: "renewal_processing_failed" }); }
+  }
+  return results;
+}
+export async function refuseRenewalBeforePayment(input: { store: RenewalStorePort; operation: RenewalReadback; reason: string; occurredAt: string }): Promise<AutomaticRenewalRunResult> {
+  const refused = await input.store.refuseBeforePayment({ operationId: input.operation.operationId, claimToken: input.operation.claimToken, reason: input.reason, occurredAt: input.occurredAt });
+  return automaticRenewalResult(refused, "refused", input.reason);
+}
+const HANDOFF_OPENS_AT_RETRY_ATTEMPT = 1;
+export async function handoffRefusal(deps: AutomaticRenewalRunDeps, operation: RenewalReadback, prepared: { cycleId: string; orderId: string; settlementIntentId: string }, externalAttemptRef: string | null, reason: string, failureClass: string, occurredAt: string): Promise<AutomaticRenewalRunResult> {
+  await deps.failureHandoff.handoffFailure({
+    idempotencyKey: `${operation.identityKey}:failure-handoff`, subscriptionId: operation.subscriptionId,
+    clientId: operation.cycleSnapshot.clientId, cycleId: prepared.cycleId, orderId: prepared.orderId,
+    paymentIntentId: prepared.settlementIntentId, retryAttempt: HANDOFF_OPENS_AT_RETRY_ATTEMPT,
+    failureClass, failureReason: reason,
+    nextRetryAt: nextRetryAttemptAt(occurredAt, HANDOFF_OPENS_AT_RETRY_ATTEMPT, undefined, failureClass),
+    occurredAt, amountMinor: operation.cycleSnapshot.pricingSnapshot.totalAmountMinor, currency: operation.cycleSnapshot.pricingSnapshot.currency,
+  });
+  await deps.settlement.recordTerminalOutcome({ operationId: operation.operationId, eventKey: `${operation.identityKey}:provider-refusal`, operationFingerprint: operation.operationFingerprint, outcome: "refused", externalRef: externalAttemptRef, reason, occurredAt });
+  return automaticRenewalResult(operation, "refused", reason);
+}

package/src/subscriptions/contracts/commands.ts

@@ -0,0 +1,46 @@
+export interface SubscriptionCommandContext {
+  actor: { kind: "customer" | "operator"; actorId: string; clientId: string };
+  subscriptionId: string; idempotencyKey: string; now: string;
+}
+export type SubscriptionCommand = SubscriptionCommandContext & (
+  | { action: "pause"; pausePreset: string; reason: string | null; survey: string | null; saveOffer: string | null }
+  | { action: "resume" | "skip" | "cancel"; reason: string | null; confirmedChargeTiming: boolean }
+  | { action: "slide"; newNextCycleAt: string; confirmedChargeTiming: boolean }
+  | { action: "edit_future_terms"; shippingAddressId: string; planDays: number; cadenceDays: number;
+      expectedTemplateVersion: number; acceptedQuoteHash: string; confirmedChargeTiming: boolean;
+      coreLines: readonly SubscriptionBundleLine[]; addonLines: readonly SubscriptionBundleLine[];
+      compositionConstraint: string }
+);
+export interface SubscriptionBundleLine { sku: string; quantity: number }
+export interface SubscriptionCommandReceipt {
+  actorId: string; idempotencyKey: string; commandFingerprint: string;
+  outcome: "applied" | "replayed" | "noop"; subscriptionId: string;
+  originalState: string; nextCycleAt: string | null; revision: string; eventId: string | null;
+}
+export type SubscriptionUnsupportedCode = "multi_cycle_prepaid_unsupported" | "native_generic_bundle_commands_unsupported" | "native_command_bound_receipts_unsupported" | "native_prepared_attempt_store_unsupported";
+export interface SubscriptionUnsupported { supported: false; refusalCode: SubscriptionUnsupportedCode }
+/** Readiness must be selected explicitly; a port declaration does not install a store. */
+export interface SubscriptionCapabilities {
+  graph: "managed" | "native";
+  multiCyclePrepaid: { supported: false; refusalCode: "multi_cycle_prepaid_unsupported" };
+  genericBundleCommands: { supported: true } | { supported: false; refusalCode: "native_generic_bundle_commands_unsupported" };
+  commandBoundReceipts: { supported: true } | { supported: false; refusalCode: "native_command_bound_receipts_unsupported" };
+  preparedAttemptStore: { supported: true } | { supported: false; refusalCode: "native_prepared_attempt_store_unsupported" };
+  retryRecovery: "unavailable" | "selected";
+  stockRecovery: "unavailable" | "selected";
+  deliveryAdmission: "required";
+  executorCount: 1;
+  defaultEnabled: false;
+}
+export interface SubscriptionCommandPort {
+  readonly capabilities: SubscriptionCapabilities;
+  /** Future term writes, actor/command receipt and events must commit atomically. */
+  apply(command: SubscriptionCommand): Promise<SubscriptionCommandReceipt | SubscriptionUnsupported>;
+}
+export interface SubscriptionActivationPort {
+  activate(input: { idempotencyKey: string; orderId: string; paymentIntentId: string;
+    paidEvidenceRef: string; paidAt: string; paymentMethodRef: string; paymentMethodKind: string;
+    checkoutKind: string }): Promise<
+      | { outcome: "noop" | "blocked"; reason: string }
+      | { outcome: "active"; subscriptionId: string; orderId: string; paymentIntentId: string; nextCycleAt: string; cadenceDays: number; replayed: boolean }>;
+}

package/src/subscriptions/contracts/dunning.ts

@@ -0,0 +1,48 @@
+export interface DunningCaseOpenInput {
+  idempotencyKey: string; subscriptionId: string; cycleId: string | null; clientId: string;
+  retryAttempt: number; nextRetryAt: string | null; failureClass: string | null;
+  failureReason: string | null; occurredAt: string; amountMinor: number | null;
+  currency: string | null; templateSlug: string; recoveryUrlPath: string | null;
+}
+export interface DunningCaseOpened {
+  caseId: string; caseStatus: string; replayed: boolean; notificationId: string | null;
+}
+export interface DunningCaseAdvanced {
+  caseId: string; caseStatus: string; notificationId: string | null;
+  retryAttempt: number | null; paused: false; pauseWindowId: null; terminal: boolean;
+}
+export type DunningRefusalCode = "case_not_open" | "recoverable_order_unavailable";
+export interface DunningCaseLifecyclePort {
+  openCase(input: DunningCaseOpenInput): Promise<DunningCaseOpened>;
+  recordFailedAttempt(input: { caseId: string; occurredAt: string; failureClass: string | null; failureReason: string | null; retryAttempt: number; nextRetryAt: string | null; templateSlug: string; recoveryUrlPath: string | null }): Promise<DunningCaseAdvanced>;
+  recordRecovery(input: { caseId: string; recoveredAt: string; templateSlug: string }): Promise<
+    | { outcome: "recovered"; caseId: string; caseStatus: string; replayed: boolean; notificationId: string | null }
+    | { outcome: "refused"; caseId: string; caseStatus: string; refusalCode: DunningRefusalCode }>;
+  issueRecoveryLink(input: { caseId: string; tokenHash: string; expiresAt: string }): Promise<
+    | { outcome: "issued"; orderId: string }
+    | { outcome: "refused"; refusalCode: DunningRefusalCode }>;
+}
+export interface RenewalRetryState {
+  rowPresent: boolean; retryAttempt: number | null; nextRetryAt: string | null;
+}
+export interface RenewalRetryObligation {
+  operationId: string; subscriptionId: string; cycleId: string; orderId: string;
+  settlementIntentId: string; logicalCycleNumber: number; nativeRenewalCounter: number;
+  retryAttempt: number; externalAttemptSequence: number; nextRetryAt: string | null;
+  failureClass: string | null; failureReason: string | null; occurredAt: string;
+  identityKey: string; requestFingerprint: string;
+  disposition: "retry_scheduled" | "payment_failed" | "paid";
+}
+export interface RenewalRecoveryAuthorization {
+  tokenId: string; tokenHash: string; caseId: string; clientId: string;
+  authUserId: string | null; subscriptionId: string; cycleId: string; orderId: string;
+  payerAccountRef: string | null; purpose: "repair_payment" | "resume_subscription";
+  retryAttempt: number; paymentMethodRef: string; paymentMethodKind: string;
+  expiresAt: string; usedAt: string | null; revokedAt: string | null; requestedAt: string;
+}
+export interface RenewalFailureHandoffPort {
+  handoffFailure(input: { idempotencyKey: string; subscriptionId: string; clientId: string;
+    cycleId: string; orderId: string; paymentIntentId: string; retryAttempt: number;
+    failureClass: string; failureReason: string; nextRetryAt: string | null;
+    occurredAt: string; amountMinor: number | null; currency: string | null }): Promise<{ caseId: string | null; replayed: boolean }>;
+}

package/src/subscriptions/contracts/index.ts

@@ -0,0 +1,6 @@
+export type { RenewalSchedule, RenewalIdentity, RenewalAdmission, RenewalLine, RenewalCycleCorrelation, RenewalTemplateSnapshot, RenewalPricingSnapshot, RenewalOrderSnapshot, RenewalFrozenSnapshot, RenewalDue, RenewalOperationState, RenewalReadback, RenewalPaymentEvidence, RenewalTransactionUnits, RenewalReservationResult, RenewalPreparedSettlement, RenewalStorePort, RenewalSettlementPort, RenewalExecutionRequest, RenewalPaymentRail, RenewalResult } from "./renewal.js";
+export type { DunningCaseOpenInput, DunningCaseOpened, DunningCaseAdvanced, DunningRefusalCode, DunningCaseLifecyclePort, RenewalRetryState, RenewalRetryObligation, RenewalRecoveryAuthorization, RenewalFailureHandoffPort } from "./dunning.js";
+export type { StockWaitRecoveryBinding, StockWaitDeficit, StockWaitCase, StockWaitStorePort } from "./stockWait.js";
+export type { SubscriptionCommandContext, SubscriptionCommand, SubscriptionBundleLine, SubscriptionCommandReceipt, SubscriptionUnsupportedCode, SubscriptionUnsupported, SubscriptionCapabilities, SubscriptionCommandPort, SubscriptionActivationPort } from "./commands.js";
+export type { SubscriptionLifecycleFact, SubscriptionLifecycleMessageDescriptor, SubscriptionLifecycleMessagePort } from "./messages.js";
+export type { SubscriptionRenewalOutcome, HostedRenewalDue, SubscriptionRenewalChargeResult, SubscriptionCycleSnapshotResult, SubscriptionCycleOrderInput, SubscriptionCycleOrderResult, SubscriptionReservationPreflightResult, SubscriptionRenewalPersistencePort, FailurePropagationKind, FailurePropagationContext, CycleRetryState, DunningCaseOpenOutcome, CycleChargeFailurePropagationPort, FailurePropagationResult, RenewalPrepareInput, RenewalAttemptResult, RenewalIntentResult, RenewalPaymentPort, RenewalExecutionPort, RenewalDeliveryAdmission, RenewalAllowedAdmission, RenewalDeliveryClient, RenewalFailureDeps, RenewalPreflightDeps, RenewalCycleDeps, RenewalExecutionContext, RenewalOutcomeContext, RenewalReplayContext, RenewalPreparedAttemptPrepareInput, RenewalPreparedAttemptPersistenceResult, RenewalPreparedAttemptFinalizeInput, RenewalPreparedAttemptPersistencePort } from "./renewal.js";

package/src/subscriptions/contracts/messages.ts

@@ -0,0 +1,18 @@
+export type SubscriptionLifecycleFact = {
+  factId: string; idempotencyKey: string; subscriptionId: string; clientId: string;
+  cycleId: string | null; caseId: string | null; orderId: string | null;
+  occurredAt: string; firstRecordedAt: string;
+} & (
+  | { kind: "payment_failed" | "payment_expired"; retryAttempt: number; nextRetryAt: string | null; failureClass: string | null; amountMinor: number | null; currency: string | null }
+  | { kind: "payment_recovered"; paymentEvidenceRef: string }
+  | { kind: "stock_wait_started" | "stock_wait_resumed"; frozenFingerprint: string }
+  | { kind: "winback_eligible"; cancelledAt: string; paymentMethodRef: string }
+);
+/** M04 receives a descriptor; host owns copy, recipient, consent and transport. */
+export interface SubscriptionLifecycleMessageDescriptor {
+  fact: SubscriptionLifecycleFact; messageKey: string; templateSlug: string;
+  recipientRef: string; locale: string; recoveryUrlPath: string | null;
+}
+export interface SubscriptionLifecycleMessagePort {
+  enqueue(descriptor: SubscriptionLifecycleMessageDescriptor): Promise<{ notificationId: string; replayed: boolean }>;
+}

package/src/subscriptions/contracts/renewal.ts

@@ -0,0 +1,325 @@
+import type {
+  PaymentAttemptStatus, PaymentExecutionBaseInput, PaymentExecutionBaseResult,
+  PaymentProviderCapabilityDescriptor, ProviderAttemptIdentity,
+} from "@openlup/core/payment";
+
+/** Structural hosted-cycle contracts; native vocabulary is bound by the caller. */
+export type SubscriptionRenewalOutcome = "charged" | "requires_action" | "failed" | "skipped";
+export interface HostedRenewalDue {
+  subscriptionId: string; nextCycleAt: string; providerKind: string;
+  providerMethodRef: string | null;
+}
+export interface SubscriptionRenewalChargeResult {
+  subscriptionId: string; outcome: SubscriptionRenewalOutcome; cycleId: string | null;
+  cycleNumber: number | null; orderId: string | null; paymentIntentId: string | null;
+  attemptStatus: PaymentAttemptStatus | null; replayed: boolean; dunningCaseId?: string | null;
+  retryAttempt?: number | null; applyReplayed?: boolean; dunningPropagationFailed?: boolean; reason?: string;
+  admissionDeferralReference?: string;
+}
+export interface SubscriptionCycleSnapshotResult {
+  cycleNumber: number; retryAttempt: number; providerAttemptSequence: number;
+  templateSnapshot: Record<string, unknown>; pricingSnapshot: Record<string, unknown>;
+  orderSnapshot: Record<string, unknown>;
+}
+export interface SubscriptionCycleOrderInput {
+  idempotencyKey: string; subscriptionId: string; cycleNumber: number; scheduledAt: string;
+  templateSnapshot: Record<string, unknown>; pricingSnapshot: Record<string, unknown>;
+  orderSnapshot: Record<string, unknown>;
+}
+export interface SubscriptionCycleOrderResult {
+  cycleId: string; orderRef: string; orderUuid: string; paymentRef: string; replayed: boolean;
+}
+export interface SubscriptionReservationPreflightResult {
+  ok: boolean; reason: string | null; itemsChecked: number; reacquired: number;
+}
+export interface SubscriptionRenewalPersistencePort<M extends string | null | undefined = string | null | undefined> {
+  buildCycleSnapshots(input: { subscriptionId: string; scheduledAt: string }): Promise<SubscriptionCycleSnapshotResult>;
+  createCycleOrder(input: SubscriptionCycleOrderInput): Promise<SubscriptionCycleOrderResult>;
+  preflightReservation(input: { orderId: string; now: string }): Promise<SubscriptionReservationPreflightResult>;
+  readMandateRecurringModel(providerKind: string, providerMethodRef: string | null): Promise<M>;
+  noteRowOutcome(input: { subscriptionId: string; scheduledAt: string; errorKey: string | null }): Promise<void>;
+}
+
+export type FailurePropagationKind =
+  | "off_session_requires_action"
+  | "provider_declined"
+  | "preflight_block";
+export interface FailurePropagationContext {
+  kind: FailurePropagationKind;
+  executionIdempotencyKey: string;
+  providerIdempotencyKey: string;
+  providerRequestFingerprint: string;
+  paymentIntentId: string;
+  cycleId: string;
+  subscriptionId: string;
+  orderUuid: string;
+  providerKind: string;
+  failureReason: string;
+  failureClassification?: { failureClass: string; decidedBy: string } | null;
+  occurredAt: string;
+  attemptAlreadyPrepared?: boolean;
+}
+export interface CycleRetryState {
+  retryAttempt: number | null;
+  nextRetryAt: string | null;
+  rowPresent: boolean;
+}
+export type DunningCaseOpenOutcome =
+  | { status: "opened"; caseId: string | null }
+  | { status: "rejected"; reason: string; code?: string }
+  | { status: "unavailable"; reason: string };
+export interface CycleChargeFailurePropagationPort {
+  recordBlockedPreflightAttempt(input: {
+    idempotencyKey: string;
+    paymentIntentId: string;
+    providerKind: string;
+    providerIdempotencyKey: string;
+    providerRequestFingerprint: string;
+    failureReason: string;
+  }): Promise<void>;
+  readDurableAttemptInstant(input: {
+    paymentIntentId: string;
+    attemptIdempotencyKey: string;
+  }): Promise<string | null>;
+  applyFailedResult(input: {
+    idempotencyKey: string;
+    paymentIntentId: string;
+    occurredAt: string;
+    failureReason: string;
+    failureClassification: { failureClass: string; decidedBy: string };
+  }): Promise<{ replayed: boolean }>;
+  readCycleRetryState(cycleId: string): Promise<CycleRetryState>;
+  openDunningCase(input: {
+    idempotencyKey: string;
+    cycleId: string;
+    subscriptionId: string;
+    orderUuid: string;
+    paymentIntentId: string;
+    retryAttempt: number;
+    nextRetryAt: string | null;
+    failureReason: string;
+    occurredAt: string;
+    failureClass: string;
+  }): Promise<DunningCaseOpenOutcome>;
+}
+export interface FailurePropagationResult {
+  dunningCaseId: string | null;
+  retryAttempt: number | null;
+  applyReplayed: boolean;
+  dunningPropagationFailed: boolean;
+}
+
+export type RenewalPrepareInput<P extends string> =
+  Parameters<RenewalPreparedAttemptPersistencePort<P, string>["prepareProviderAttempt"]>[0];
+export type RenewalAttemptResult<N extends string> =
+  Awaited<ReturnType<RenewalPreparedAttemptPersistencePort<string, N>["finalizeProviderAttempt"]>>;
+export interface RenewalIntentResult { paymentIntentId: string; replayed: boolean }
+export interface RenewalPaymentPort<CI, IR extends RenewalIntentResult, P extends string, N extends string>
+  extends RenewalPreparedAttemptPersistencePort<P, N> {
+  createIntent(input: CI): Promise<IR>;
+}
+export interface RenewalExecutionPort<I extends PaymentExecutionBaseInput, R extends PaymentExecutionBaseResult> {
+  execute(input: I): Promise<R>;
+}
+export interface RenewalDeliveryAdmission { allowed: boolean; state: string; reason: string }
+export type RenewalAllowedAdmission = RenewalDeliveryAdmission & { allowed: true };
+export interface RenewalDeliveryClient {
+  admitDeliveryAlignment(input: { subscriptionId: string; scheduledAt: string; asOf: string }): Promise<RenewalDeliveryAdmission>;
+}
+export interface RenewalFailureDeps {
+  chargeFailurePropagation: CycleChargeFailurePropagationPort;
+  now?: () => string;
+}
+export interface RenewalPreflightDeps<CI, IR extends RenewalIntentResult, M extends string | null | undefined>
+  extends RenewalFailureDeps {
+  persistence: SubscriptionRenewalPersistencePort<M>;
+  paymentPort: { createIntent(input: CI): Promise<IR> };
+}
+export interface RenewalCycleDeps<CI, IR extends RenewalIntentResult, P extends string, N extends string,
+  I extends PaymentExecutionBaseInput, R extends PaymentExecutionBaseResult, M extends string | null | undefined>
+  extends RenewalPreflightDeps<CI, IR, M> {
+  paymentPort: RenewalPaymentPort<CI, IR, P, N>;
+  executionPort: RenewalExecutionPort<I, R>;
+  deliveryAlignment: RenewalDeliveryClient;
+  capability: PaymentProviderCapabilityDescriptor;
+  deliveryAlignmentAdmission?: RenewalAllowedAdmission;
+}
+/** Local references, never a snapshot of the original due/ports or their getters. */
+export interface RenewalExecutionContext<IR extends RenewalIntentResult, M extends string | null | undefined, F extends string> {
+  snapshots: SubscriptionCycleSnapshotResult;
+  cycleOrder: SubscriptionCycleOrderResult;
+  intent: IR;
+  totalGrossMinor: number;
+  executionIdempotencyKey: string;
+  attemptIdentity: ProviderAttemptIdentity;
+  providerFlow: F;
+  paymentMethodRecurringModel: M | undefined;
+}
+export interface RenewalOutcomeContext {
+  executionIdempotencyKey: string;
+  attemptIdentity: ProviderAttemptIdentity;
+  intent: RenewalIntentResult;
+  cycleOrder: Pick<SubscriptionCycleOrderResult, "cycleId" | "orderUuid" | "replayed">;
+  snapshots: Pick<SubscriptionCycleSnapshotResult, "cycleNumber">;
+  finalizedAttempt: { status: PaymentAttemptStatus };
+}
+export interface RenewalReplayContext {
+  cycleId: string; cycleNumber: number; orderId: string; paymentIntentId: string;
+  executionIdempotencyKey: string; providerIdempotencyKey: string;
+  providerRequestFingerprint: string; providerKind: string;
+}
+
+/** Durable preparation facts; provider admission belongs to the caller. */
+export interface RenewalPreparedAttemptPrepareInput<P extends string = string> {
+  idempotencyKey: string;
+  paymentIntentId: string;
+  provider: P;
+  providerIdempotencyKey: string;
+  providerRequestFingerprint: string;
+  providerFlow: string;
+  paymentMethodRef?: string | null;
+  requestPayload: Record<string, unknown>;
+}
+
+export interface RenewalPreparedAttemptPersistenceResult<N extends string = string> {
+  paymentAttemptId: string;
+  status: PaymentAttemptStatus;
+  replayed: boolean;
+  providerAttemptId: string | null;
+  providerSessionId: string | null;
+  nextActionKind: N | null;
+}
+
+export interface RenewalPreparedAttemptFinalizeInput<N extends string = string> extends Pick<
+  PaymentExecutionBaseResult,
+  "providerAttemptId" | "providerSessionId" | "attemptStatus" | "requestPayload" | "responsePayload"
+> {
+  idempotencyKey: string;
+  paymentIntentId: string;
+  paymentAttemptId: string;
+  providerIdempotencyKey: string;
+  providerRequestFingerprint: string;
+  nextActionKind: N | null;
+}
+
+/** Only persistence capabilities needed by interactive attempt ordering. */
+export interface RenewalPreparedAttemptPersistencePort<P extends string = string, N extends string = string> {
+  prepareProviderAttempt(input: RenewalPreparedAttemptPrepareInput<P>): Promise<RenewalPreparedAttemptPersistenceResult<N>>;
+  finalizeProviderAttempt(input: RenewalPreparedAttemptFinalizeInput<N>): Promise<RenewalPreparedAttemptPersistenceResult<N>>;
+}
+
+
+/** Original text is an identity input; instant is for comparisons only. */
+export interface RenewalSchedule {
+  subscriptionId: string;
+  scheduledAt: string;
+  scheduledInstant: number;
+}
+export interface RenewalIdentity {
+  cycleIdempotencyKey: string;
+  executionIdempotencyKey: string;
+  externalIdempotencyKey: string;
+  requestFingerprint: string;
+}
+export type RenewalAdmission =
+  | { allowed: true; state: string; reason: string }
+  | { allowed: false; state: string; reason: string; deferred: true; caseRef?: string }
+  | { allowed: false; state: string; reason: string; deferred: false };
+export interface RenewalLine {
+  lineOrdinal: number; sku: string; quantity: number; unitAmountMinor: number;
+}
+/** Logical numbering is evidence-bound, never a universal nativeCounter + 1. */
+export type RenewalCycleCorrelation =
+  | { status: "correlated"; logicalCycleNumber: number; nativeRenewalCounter: number | null; activationCycleId: string | null; evidenceRef: string }
+  | { status: "ambiguous"; logicalCycleNumber: null; nativeRenewalCounter: number | null; activationCycleId: string | null; reason: string };
+export interface RenewalTemplateSnapshot {
+  templateId: string; version: number; cadenceDays: number; lines: readonly RenewalLine[];
+}
+export interface RenewalPricingSnapshot {
+  currency: string; totalAmountMinor: number; shippingAmountMinor: number;
+  agreementPolicy: "lock_until_edit"; proration: "none";
+}
+export interface RenewalOrderSnapshot {
+  shippingAddressRef: string | null; shippingQuoteRef: string | null;
+  acquisitionRef: string | null; lines: readonly RenewalLine[];
+}
+export interface RenewalFrozenSnapshot extends RenewalSchedule {
+  contractVersion: "platform.subscription.renewal.v1";
+  clientId: string; frozenRevision: string; frozenFingerprint: string;
+  cycle: RenewalCycleCorrelation; retryAttempt: number; externalAttemptSequence: number;
+  templateSnapshot: RenewalTemplateSnapshot;
+  pricingSnapshot: RenewalPricingSnapshot;
+  orderSnapshot: RenewalOrderSnapshot;
+  stockSourceKey: string; settlementChannelKey: string; authorizationRef: string;
+  payerAccountRef: string | null; unattendedChargeAuthorizedAt: string;
+}
+export interface RenewalDue extends RenewalSchedule {
+  clientId: string; cadenceDays: number; cycle: RenewalCycleCorrelation; currency: string;
+  stockSourceKey: string; settlementChannelKey: string; authorizationRef: string;
+  payerAccountRef: string | null; unattendedChargeAuthorizedAt: string;
+  deliveryAdmission: "allowed" | "blocked"; deliveryBlockReason: string | null;
+}
+export type RenewalOperationState = "claimed" | "reserved" | "attempt_prepared" | "succeeded" | "refused";
+export interface RenewalReadback extends RenewalSchedule {
+  contractVersion: "platform.subscription.renewal.v1";
+  acquired: boolean; replayed: boolean; reason: string;
+  operationId: string; identityKey: string; operationFingerprint: string;
+  cycle: RenewalCycleCorrelation; state: RenewalOperationState;
+  claimToken: string; claimGeneration: number; leaseExpiresAt: string;
+  cycleSnapshot: RenewalFrozenSnapshot;
+  externalAttemptRef: string | null; externalAttemptAcknowledgedAt: string | null;
+  terminalOutcome: "succeeded" | "refused" | null; terminalReason: string | null; terminalAt: string | null;
+  reservationId: string | null; cycleId: string | null; orderId: string | null; settlementIntentId: string | null;
+}
+/** M07 verified truth. Nullable money is not positive matching evidence. */
+export interface RenewalPaymentEvidence {
+  status: "succeeded" | "failed" | "pending" | "unknown";
+  disposition: "observed" | "ambiguous" | "late_positive";
+  operationId: string; eventKey: string; requestFingerprint: string;
+  verifiedEvidenceRef: string; externalAttemptRef: string | null;
+  occurredAt: string | null; observedAt: string; firstRecordedAt: string;
+  amountMinor: number | null; currency: string | null; reason: string | null;
+}
+/** Payment execution is outside all SQL transactions. */
+export type RenewalTransactionUnits =
+  | { graph: "native"; prepare: "cycle_order_items_settlement_reservation_attempt"; outcome: "settlement_outcome_schedule_counter_reservation"; recovery: "settlement_cycle_receipt_case_counter" }
+  | { graph: "managed"; prepare: "create_cycle_order_then_prepare_attempt"; failure: "record_attempt_then_apply_result_then_open_case"; recovery: "authorize_method_then_schedule" };
+export interface RenewalReservationResult {
+  reserved: boolean; replayed: boolean; reservationId: string | null;
+  status: "held" | "committed" | "consumed" | "released" | "expired" | "refused";
+  reason: string | null;
+}
+export interface RenewalPreparedSettlement {
+  contractVersion: "platform.subscription.renewal.v1"; replayed: boolean;
+  operationId: string; operationFingerprint: string; cycleId: string;
+  orderId: string; settlementIntentId: string; state: "attempt_prepared";
+}
+export interface RenewalStorePort {
+  readonly transactions: RenewalTransactionUnits;
+  listDue(limit: number, asOf: string): Promise<RenewalDue[]>;
+  buildCycleSnapshots(input: RenewalSchedule): Promise<RenewalFrozenSnapshot>;
+  readMandateEvidence(input: RenewalSchedule): Promise<{ authorized: boolean; authorizationRef: string; authorizedAt: string | null }>;
+  admitDeliveryAlignment(input: RenewalSchedule & { occurredAt: string }): Promise<RenewalAdmission>;
+  claimDue(input: { snapshot: RenewalFrozenSnapshot; workerId: string; leaseSeconds?: number; now: string }): Promise<RenewalReadback>;
+  readRenewal(identityKey: string): Promise<RenewalReadback | null>;
+  refuseBeforePayment(input: { operationId: string; claimToken: string; reason: string; occurredAt: string }): Promise<RenewalReadback>;
+}
+export interface RenewalSettlementPort {
+  prepareRenewal(input: { operationId: string; claimToken: string; now: string }): Promise<RenewalPreparedSettlement>;
+  acknowledgeExternalAttempt(input: { operationId: string; operationFingerprint: string; externalAttemptRef: string; acknowledgedAt: string }): Promise<RenewalReadback>;
+  recordTerminalOutcome(input: { operationId: string; eventKey: string; operationFingerprint: string; outcome: "succeeded" | "refused"; externalRef?: string | null; reason?: string | null; occurredAt: string }): Promise<RenewalReadback>;
+}
+export interface RenewalExecutionRequest extends RenewalIdentity {
+  paymentIntentId: string; amountMinor: number; currency: string; mode: string;
+  orderRef: string; orderId: string; flow: string; customerRef: string | null;
+  paymentMethodRef: string; recurringModel: string | null; clientId: string;
+  payer: { email: string | null; name: string | null } | null;
+}
+export interface RenewalPaymentRail {
+  execute(input: RenewalExecutionRequest): Promise<{ status: "succeeded" | "failed" | "requires_action" | "pending" | "unknown"; externalAttemptRef: string | null; failure?: { reason: string; failureClass: string } }>;
+  findExternalAttempt(input: { settlementIntentId: string }): Promise<string | null>;
+  readOutcome(input: { externalAttemptRef: string; settlementIntentId: string; orderId: string; subscriptionId: string; amountMinor: number; currency: string }): Promise<RenewalPaymentEvidence>;
+}
+export type RenewalResult =
+  | { outcome: "deferred"; subscriptionId: string; scheduledAt: string; reason: string; caseRef?: string }
+  | { outcome: "charged" | "requires_action" | "failed" | "skipped"; subscriptionId: string; cycleId: string | null; cycleNumber: number | null; orderId: string | null; paymentIntentId: string | null; attemptStatus: string | null; replayed: boolean; dunningCaseId?: string | null; retryAttempt?: number | null; applyReplayed?: boolean; dunningPropagationFailed?: boolean; reason?: string };

package/src/subscriptions/contracts/stockWait.ts

@@ -0,0 +1,34 @@
+import type { RenewalFrozenSnapshot, RenewalReadback, RenewalSchedule } from "./renewal.js";
+export interface StockWaitRecoveryBinding {
+  caseId: string | null; cycleId: string | null; orderId: string | null;
+  paymentId: string | null; engineIdempotencyKey: string | null;
+}
+export interface StockWaitDeficit {
+  skuId: string; sku: string; displayName: string; size: string | null;
+  required: number; reserved: number; available: number; missing: number;
+}
+export interface StockWaitCase extends RenewalSchedule {
+  caseId: string; clientId: string; state: "waiting" | "stock_secured" | "resumed" | "closed";
+  frozenSnapshot: RenewalFrozenSnapshot; frozenFingerprint: string;
+  binding: StockWaitRecoveryBinding; deficits: readonly StockWaitDeficit[];
+  fulfillmentRef: string | null; blockReason: string | null;
+  openedAt: string; checkedAt: string | null; selectedAt: string | null;
+  securedAt: string | null; resumedAt: string | null; closedAt: string | null;
+  startedNoticeKey: string; resumedNoticeKey: string; noticeEligible: boolean;
+}
+/** All-line reserve/reacquire and the wait transition share a DB transaction.
+ * A shortage rolls back the subtransaction, retaining previous commitments;
+ * record the wait outside that failed subtransaction. Technical failure is unknown.
+ */
+export interface StockWaitStorePort {
+  listCandidates(input: { limit: number; asOf: string }): Promise<StockWaitCase[]>;
+  readFrozenCase(input: StockWaitRecoveryBinding): Promise<StockWaitCase | null>;
+  reserveAndTransition(input: { caseId: string; frozenFingerprint: string; now: string }): Promise<StockWaitCase>;
+  /** Only elapsed, unprepared, unacknowledged, stock-only refusals may reset.
+   * Requires unchanged schedule/fingerprint and no payment artifacts or outcomes.
+   * Rotate fencing generation atomically with reacquisition. Never reset ambiguity.
+   */
+  recoverRefusedSchedule(input: { operationId: string; caseId: string; claimGeneration: number; frozenFingerprint: string; scheduledAt: string; now: string }): Promise<
+    | { outcome: "recovered"; operation: RenewalReadback; replayed: boolean }
+    | { outcome: "refused"; reason: "not_stock_only" | "external_ownership" | "stale_snapshot" | "lease_active" | "inventory_unavailable" }>;
+}

package/src/subscriptions/index.ts

@@ -0,0 +1,24 @@
+export { renewalIdentity } from "./renewalIdentity.js";
+export const NATIVE_SUBSCRIPTION_CAPABILITIES = Object.freeze({
+  graph: "native",
+  multiCyclePrepaid: Object.freeze({ supported: false, refusalCode: "multi_cycle_prepaid_unsupported" }),
+  genericBundleCommands: Object.freeze({ supported: false, refusalCode: "native_generic_bundle_commands_unsupported" }),
+  commandBoundReceipts: Object.freeze({ supported: false, refusalCode: "native_command_bound_receipts_unsupported" }),
+  preparedAttemptStore: Object.freeze({ supported: false, refusalCode: "native_prepared_attempt_store_unsupported" }),
+  retryRecovery: "selected", stockRecovery: "unavailable",
+  deliveryAdmission: "required", executorCount: 1, defaultEnabled: false,
+} as const satisfies import("./contracts/commands.js").SubscriptionCapabilities);
+export { executeRenewalCycle, prepareRenewalAttempt, checkRenewalDeliveryAdmission } from "./renewalCycleMechanism.js";
+export type { RenewalCyclePolicy } from "./renewalCycleMechanism.js";
+export { recordRenewalPreflightBlock, replayRenewalAttempt, declinedRenewalOutcome, requiresActionRenewalOutcome } from "./renewalCycleRefusalMechanism.js";
+export type { RenewalPreflightPolicy, RenewalReplayPolicy, RenewalOutcomePolicy } from "./renewalCycleRefusalMechanism.js";
+export { propagateRenewalFailure } from "./renewalCycleFailureMechanism.js";
+export type { RenewalFailurePolicy } from "./renewalCycleFailureMechanism.js";
+export { runAutomaticSubscriptionRenewals, runOneAutomaticSubscriptionRenewal, correlatedLogicalCycle } from "./automaticRenewal.js";
+export type { AutomaticRenewalRunStatus, AutomaticRenewalRunResult, AutomaticRenewalRunDeps, AutomaticRenewalPolicy } from "./automaticRenewal.js";
+export { createPostgresRenewalStore } from "./postgresRenewalStore.js";
+export type { NativeRenewalCodec, SubscriptionQueryExecutor } from "./postgresRenewalStore.js";
+export { createPostgresRetryStore } from "./postgresRetryStore.js";
+export type { NativeRetryFailure, NativeRetryRequest, NativeRetryPositive, NativeRetryPreparation, NativeRetryRow } from "./postgresRetryStore.js";
+export { createPostgresRetryLifecycleBinding } from "./postgresRetryStore.js";
+export type { NativeRetryLifecycleBinding } from "./postgresRetryStore.js";

package/src/subscriptions/paymentOutcomes.ts

@@ -0,0 +1,23 @@
+import type { RenewalPaymentRail, RenewalReadback } from "./contracts/renewal.js";
+import type { AutomaticRenewalRunDeps, AutomaticRenewalRunResult } from "./automaticRenewal.js";
+import { automaticRenewalResult, handoffRefusal } from "./automaticRenewalExecution.js";
+/** H4: only explicit verified matching M07 evidence may become positive local truth. */
+export async function readAndApplyProviderOutcome(deps: AutomaticRenewalRunDeps, operation: RenewalReadback, prepared: { cycleId: string; orderId: string; settlementIntentId: string }, rail: RenewalPaymentRail, externalAttemptRef: string, occurredAt: string): Promise<AutomaticRenewalRunResult> {
+  const money = operation.cycleSnapshot.pricingSnapshot;
+  const observed = await rail.readOutcome({ externalAttemptRef, settlementIntentId: prepared.settlementIntentId, orderId: prepared.orderId, subscriptionId: operation.subscriptionId, amountMinor: money.totalAmountMinor, currency: money.currency });
+  if (observed.amountMinor !== null && observed.amountMinor !== money.totalAmountMinor) throw new Error("subscription_renewal_provider_amount_mismatch");
+  if (observed.currency !== null && observed.currency.toUpperCase() !== money.currency.toUpperCase()) throw new Error("subscription_renewal_provider_currency_mismatch");
+  if (observed.status === "pending" || observed.status === "unknown") return automaticRenewalResult(operation, "awaiting_provider", `provider_${observed.status}`);
+  if (observed.operationId !== operation.operationId || observed.requestFingerprint !== operation.operationFingerprint
+    || observed.externalAttemptRef !== externalAttemptRef || !observed.verifiedEvidenceRef || !observed.eventKey
+    || !observed.firstRecordedAt || !observed.observedAt) throw new Error("subscription_renewal_verified_evidence_required");
+  if (observed.disposition === "ambiguous") return automaticRenewalResult(operation, "awaiting_provider", "provider_ambiguous");
+  const terminalAt = observed.occurredAt ?? occurredAt;
+  if (observed.status === "failed") {
+    const reason = observed.reason ?? "provider_failed";
+    return handoffRefusal(deps, operation, prepared, externalAttemptRef, reason, deps.policy.classifyFailure(reason), terminalAt);
+  }
+  if (observed.amountMinor === null || observed.currency === null || observed.occurredAt === null) return automaticRenewalResult(operation, "awaiting_provider", "provider_positive_evidence_incomplete");
+  await deps.settlement.recordTerminalOutcome({ operationId: operation.operationId, eventKey: `${operation.identityKey}:provider-success:${externalAttemptRef}`, operationFingerprint: operation.operationFingerprint, outcome: "succeeded", externalRef: externalAttemptRef, occurredAt: terminalAt });
+  return automaticRenewalResult(operation, "succeeded", null);
+}