@openlup/platform 0.22.0 → 0.24.0

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);
+}

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]);
+    },
+  };
+}