@openlup/platform 0.24.0 → 0.26.0

package/src/communications/contracts/subscriptionPaymentExpired.ts

@@ -21,8 +21,9 @@ export interface SubscriptionPaymentExpiredEmailVars {
    */
   cause?: PaymentFailureCustomerCause | null;
   /**
-   * Recovery-link URL for the case's `resume_subscription` token. When present
-   * the template renders the resume CTA; when absent it keeps the support-led
+   * Recovery-link URL for the case's payment-recovery token. Current exhaustion
+   * uses `repair_payment`; legacy expired cases may carry `resume_subscription`.
+   * When present the template renders the recovery CTA; otherwise it keeps the support-led
    * wording, because a button with no destination is worse than no button.
    */
   recoveryUrl?: string | null;
@@ -51,7 +52,7 @@ export function createSubscriptionPaymentExpiredContentFactory(input: {
     const causeSentence = subscriptionPaymentCauseSentence(locale, vars.cause ?? "unknown");
     const detail = [
       // Leads the box for the same reason as in the failed notice: it answers the
-      // question the paused subscription raises, before the figures.
+      // question the unsuccessful payment raises, before the figures.
       ...(causeSentence ? [causeSentence] : []),
       ...(recoveryUrl
         ? [

package/src/communications/contracts/subscriptionPaymentFailed.ts

@@ -19,9 +19,10 @@ export interface SubscriptionPaymentFailedEmailVars {
   recoveryUrl?: string | null;
   /**
    * Pre-formatted calendar day of the scheduled next charge, in the merchant's
-   * zone (e.g. "11.08.2026"). The dunning row that selects THIS template always
-   * carries a scheduled retry, so in production this is present; null keeps the
-   * pre-date sentence rather than printing a placeholder date.
+   * zone (e.g. "11.08.2026"). Present only when a retry is actually scheduled:
+   * a first-rung hard decline selects this template with no next retry, and
+   * `retryScheduled: false` renders the no-retry copy. null/absent keeps the
+   * sentence without a date rather than printing a placeholder date.
    */
   nextRetryDateLabel?: string | null;
   /** Card scheme as stored on the method's consent snapshot, e.g. "visa". */
@@ -72,11 +73,10 @@ export function createSubscriptionPaymentFailedContentFactory(input: {
     // also why it is PREPENDED and never appended — the retry sentence must stay
     // last (see below).
     const causeSentence = subscriptionPaymentCauseSentence(locale, vars.cause ?? "unknown");
-    // Only an explicit `false` turns the promises off. Absent means "no producer
-    // told us", and the only rail that exists always schedules a retry, so absent
-    // must keep rendering today's copy rather than the safer-sounding new copy:
-    // telling a customer no attempt is coming when one is would push them to
-    // cancel a subscription that was about to recover on its own.
+    // Only an explicit `false` turns the retry promises off. Absence preserves
+    // the legacy rendering default; it does not prove a retry is scheduled.
+    // Producers must pass the actual schedule fact when retries have stopped,
+    // including class termination or exhaustion.
     const retryScheduled = vars.retryScheduled !== false;
     const detail = [
       ...(causeSentence ? [causeSentence] : []),

package/src/composition/index.ts

@@ -20,3 +20,4 @@ export { createCatalogContribution, type CatalogContributionInput } from "./cata
 export { createInventoryContribution } from "./inventoryContribution.js";
 export { createShippingContribution } from "./shippingContribution.js";
 export { createFulfillmentContribution } from "./fulfillmentContribution.js";
+export { createSubscriptionContribution } from "./subscriptionContribution.js";

package/src/composition/subscriptionContribution.ts

@@ -0,0 +1,25 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+
+/** One selected subscription job; no second scheduler or automatic registration. */
+export function createSubscriptionContribution(input: {
+  version: string;
+  requiredSchema: RequiredSchema;
+  run: (() => Promise<unknown>) | null;
+  cadenceSeconds: number;
+}) {
+  if (!Number.isFinite(input.cadenceSeconds) || input.cadenceSeconds <= 0) throw new Error("subscription_cadence_invalid");
+  const schedules = input.run ? [{ id: "subscriptions-renewal", cadenceSeconds: input.cadenceSeconds, run: input.run }] : [];
+  const contribution: Contribution = {
+    manifest: {
+      name: "@openlup/platform", version: input.version, kind: "rail",
+      module: { id: "subscriptions", kind: "capability", provides: ["./subscriptions", "./subscriptions/contracts"], dependsOn: [] },
+      emits: [], handles: [], schedules: schedules.map(({ id, cadenceSeconds }) => ({ id, cadenceSeconds })),
+      env: [], requiredPorts: ["run"], routes: [], requiredSchema: input.requiredSchema,
+    }, handlers: [], schedules, routes: [],
+  };
+  return {
+    contributions: [contribution],
+    ports: input.run ? { "@openlup/platform/subscriptions:run": input.run } : {},
+    triggers: Object.fromEntries(schedules.map(schedule => [`@openlup/platform/subscriptions:${schedule.id}`, schedule.run])),
+  };
+}

package/src/inventory/index.ts

@@ -20,3 +20,5 @@ export { forecastSubscriptionInventoryShortages, buildSubscriptionInventoryForec
 export { calculateSubscriptionForecastSkus, calculateSubscriptionForecastTotals } from "./subscriptionForecastCalculation.js";
 export { INVENTORY_MIGRATIONS } from "./sql.js";
 export { createInventoryBindings, type InventoryBindingDependencies, type InventoryBindings } from "./bindings.js";
+export { createPostgresStockAvailability } from "./postgresStockAvailability.js";
+export type { NativeStockPromise } from "./postgresStockAvailability.js";

package/src/inventory/postgresStockAvailability.ts

@@ -0,0 +1,54 @@
+import type { NewPurchaseStockRow } from "./contracts/newPurchaseStock.js";
+import type { NewPurchaseStockReadPort } from "./newPurchaseStockAvailability.js";
+
+interface StockQueryExecutor {
+  query(text: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+}
+export interface NativeStockPromise {
+  availableQuantity: number; forSaleQuantity: number; hardHoldQuantity: number;
+  safetyQuantity: number; softSubscriptionDemandQuantity: number; channelExposureQuantity: number;
+}
+function object(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("inventory_stock_response_invalid");
+  return value as Record<string, unknown>;
+}
+function quantity(value: unknown): number {
+  if ((typeof value !== "number" && typeof value !== "string") || String(value).trim() === "") throw new Error("inventory_stock_quantity_invalid");
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n < 0) throw new Error("inventory_stock_quantity_invalid");
+  return n;
+}
+/** Native read-only ATP. The fixed 14-day priority cannot be waived by a new
+ * purchase caller. Only the fenced native SQL allocator uses the renewal exemption. */
+export function createPostgresStockAvailability(executor: StockQueryExecutor, options: { sourceKey: string; now: () => string }): {
+  readPort: NewPurchaseStockReadPort;
+  availableToPromise(sku: string, asOf: string): Promise<NativeStockPromise>;
+} {
+  return {
+    async availableToPromise(sku, asOf) {
+      const row = object((await executor.query(`SELECT public.inventory_available_to_promise(
+        $1::text,$2::text,$3::timestamptz,false) AS response`, [options.sourceKey, sku, asOf])).rows[0]?.response);
+      return { availableQuantity: quantity(row.available_quantity), forSaleQuantity: quantity(row.for_sale_quantity),
+        hardHoldQuantity: quantity(row.hard_hold_quantity), safetyQuantity: quantity(row.safety_quantity),
+        softSubscriptionDemandQuantity: quantity(row.soft_subscription_demand_quantity), channelExposureQuantity: quantity(row.channel_exposure_quantity) };
+    },
+    readPort: {
+      async read(input) {
+        if (input.horizonDays !== 14 || input.excludeOrderId !== null) throw new Error("native_stock_read_options_unsupported");
+        if (!input.skus.length) return new Map();
+        const value = (await executor.query(`SELECT public.inventory_new_purchase_stock_read(
+          $1::text,$2::jsonb,$3::timestamptz) AS response`, [options.sourceKey, JSON.stringify(input.skus), options.now()])).rows[0]?.response;
+        if (!Array.isArray(value)) throw new Error("inventory_stock_response_invalid");
+        return new Map(value.map(value => {
+          const row = object(value);
+          if (typeof row.sku !== "string" || !["provider", "missing"].includes(String(row.source)) || typeof row.stale !== "boolean") throw new Error("inventory_stock_response_invalid");
+          const result: NewPurchaseStockRow = { sku: row.sku, catalogSkuId: row.catalogSkuId == null ? null : String(row.catalogSkuId),
+            source: row.source as "provider" | "missing", providerForSale: row.providerForSale == null ? null : quantity(row.providerForSale),
+            activeHolds: quantity(row.activeHolds), safetyStock: quantity(row.safetyStock), available: quantity(row.available), stale: row.stale,
+            renewalDemand: quantity(row.renewalDemand), availableForNewPurchases: quantity(row.availableForNewPurchases), excludedOrderHolds: quantity(row.excludedOrderHolds) };
+          return [result.sku, result];
+        }));
+      },
+    },
+  };
+}

package/src/subscriptions/commandExamples.ts

@@ -0,0 +1,19 @@
+import type { SubscriptionCommand, SubscriptionCommandContext, SubscriptionCommandPort } from "./contracts/commands.js";
+
+/** Neutral examples. The host authenticates and authorizes actor/client ownership first. */
+export function createSubscriptionCommandExamples(commands: SubscriptionCommandPort) {
+  const apply = (context: SubscriptionCommandContext, command: SubscriptionCommand) => {
+    if (context.actor.actorId.trim() === "" || context.actor.clientId.trim() === "") throw new Error("subscription_command_actor_required");
+    return commands.apply(command);
+  };
+  return {
+    customerSkip(context: SubscriptionCommandContext) {
+      if (context.actor.kind !== "customer") throw new Error("subscription_command_customer_required");
+      return apply(context, { ...context, action: "skip", reason: null, confirmedChargeTiming: true });
+    },
+    operatorSlide(context: SubscriptionCommandContext, newNextCycleAt: string) {
+      if (context.actor.kind !== "operator") throw new Error("subscription_command_operator_required");
+      return apply(context, { ...context, action: "slide", newNextCycleAt, confirmedChargeTiming: true });
+    },
+  };
+}

package/src/subscriptions/contracts/commands.ts

@@ -7,7 +7,9 @@ export type SubscriptionCommand = SubscriptionCommandContext & (
   | { 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;
+      expectedTemplateVersion: number;
+      /** Empty string means no quote (semantic no-op). */
+      acceptedQuoteHash: string; confirmedChargeTiming: boolean;
       coreLines: readonly SubscriptionBundleLine[]; addonLines: readonly SubscriptionBundleLine[];
       compositionConstraint: string }
 );
@@ -17,6 +19,37 @@ export interface SubscriptionCommandReceipt {
   outcome: "applied" | "replayed" | "noop"; subscriptionId: string;
   originalState: string; nextCycleAt: string | null; revision: string; eventId: string | null;
 }
+export interface SubscriptionCommandRefusal {
+  outcome: "refused";
+  /** Stable machine code; never provider, PostgreSQL diagnostic or customer text.
+   * Unrecognized native or host diagnostics map to subscription_command_invalid_input. */
+  reason:
+    | "multi_cycle_prepaid_unsupported"
+    | "subscription_command_addon_not_found"
+    | "subscription_command_bundle_total_mismatch"
+    | "subscription_command_charge_timing_not_confirmed"
+    | "subscription_command_idempotency_conflict"
+    | "subscription_command_invalid_composition_constraint"
+    | "subscription_command_invalid_input"
+    | "subscription_command_not_active"
+    | "subscription_command_operation_busy"
+    | "subscription_command_pause_forbidden"
+    | "subscription_command_payment_blocked"
+    | "subscription_command_preview_unsupported"
+    | "subscription_command_renewal_terms_missing"
+    | "subscription_command_unsupported_action"
+    | "subscription_edit_catalog_unavailable"
+    | "subscription_edit_invalid_lines"
+    | "subscription_edit_invalid_request"
+    | "subscription_edit_quote_expired"
+    | "subscription_edit_quote_required"
+    | "subscription_edit_stale_template"
+    | "subscription_edit_window_closed"
+    | "subscription_lifecycle_invalid_transition"
+    | "subscription_lifecycle_invalid_skip"
+    | "subscription_lifecycle_invalid_slide"
+    | "subscription_lifecycle_payment_blocked";
+}
 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. */
@@ -35,7 +68,7 @@ export interface SubscriptionCapabilities {
 export interface SubscriptionCommandPort {
   readonly capabilities: SubscriptionCapabilities;
   /** Future term writes, actor/command receipt and events must commit atomically. */
-  apply(command: SubscriptionCommand): Promise<SubscriptionCommandReceipt | SubscriptionUnsupported>;
+  apply(command: SubscriptionCommand): Promise<SubscriptionCommandReceipt | SubscriptionCommandRefusal | SubscriptionUnsupported>;
 }
 export interface SubscriptionActivationPort {
   activate(input: { idempotencyKey: string; orderId: string; paymentIntentId: string;

package/src/subscriptions/contracts/index.ts

@@ -1,6 +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 { StockWaitRecoveryBinding, StockWaitDeficit, StockWaitCase, StockWaitFrozenCase, StockWaitStorePort } from "./stockWait.js";
+export type { SubscriptionCommandContext, SubscriptionCommand, SubscriptionBundleLine, SubscriptionCommandReceipt, SubscriptionCommandRefusal, 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/renewal.ts

@@ -87,9 +87,10 @@ export interface CycleChargeFailurePropagationPort {
     occurredAt: string;
     failureReason: string;
     failureClassification: { failureClass: string; decidedBy: string };
-  }): Promise<{ replayed: boolean }>;
+  }): Promise<{ replayed: boolean; paymentAttemptId?: string | null }>;
   readCycleRetryState(cycleId: string): Promise<CycleRetryState>;
   openDunningCase(input: {
+    failedPaymentAttemptId: string | null;
     idempotencyKey: string;
     cycleId: string;
     subscriptionId: string;

package/src/subscriptions/contracts/stockWait.ts

@@ -5,7 +5,13 @@ export interface StockWaitRecoveryBinding {
 }
 export interface StockWaitDeficit {
   skuId: string; sku: string; displayName: string; size: string | null;
-  required: number; reserved: number; available: number; missing: number;
+  required: number;
+  /** This operation's own reserved units. */
+  reserved: number;
+  /** Free ATP, excluding this operation's own reservation. */
+  available: number;
+  /** Required units minus both reserved and available units. */
+  missing: number;
 }
 export interface StockWaitCase extends RenewalSchedule {
   caseId: string; clientId: string; state: "waiting" | "stock_secured" | "resumed" | "closed";
@@ -16,12 +22,18 @@ export interface StockWaitCase extends RenewalSchedule {
   securedAt: string | null; resumedAt: string | null; closedAt: string | null;
   startedNoticeKey: string; resumedNoticeKey: string; noticeEligible: boolean;
 }
+/** Discovery can precede the durable waiting case; never invent a case ID. */
+export interface StockWaitFrozenCase extends RenewalSchedule {
+  operationId: string; case: StockWaitCase | null;
+  frozenSnapshot: RenewalFrozenSnapshot; frozenFingerprint: string;
+  binding: StockWaitRecoveryBinding;
+}
 /** 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[]>;
+  listCandidates(input: { limit: number; asOf: string }): Promise<StockWaitFrozenCase[]>;
   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.

package/src/subscriptions/index.ts

@@ -2,10 +2,12 @@ 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" }),
+  genericBundleCommands: Object.freeze({ supported: true }),
+  commandBoundReceipts: Object.freeze({ supported: true }),
   preparedAttemptStore: Object.freeze({ supported: false, refusalCode: "native_prepared_attempt_store_unsupported" }),
-  retryRecovery: "selected", stockRecovery: "unavailable",
+  retryRecovery: "selected",
+  // Native N3 adapters exist; selection requires passing real-PG evidence.
+  stockRecovery: "unavailable",
   deliveryAdmission: "required", executorCount: 1, defaultEnabled: false,
 } as const satisfies import("./contracts/commands.js").SubscriptionCapabilities);
 export { executeRenewalCycle, prepareRenewalAttempt, checkRenewalDeliveryAdmission } from "./renewalCycleMechanism.js";
@@ -22,3 +24,28 @@ 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";
+
+export { createPostgresSubscriptionCommandStore, createPostgresSubscriptionCommands } from "./postgresCommandStore.js";
+export type { NativeSubscriptionCommand, NativeSubscriptionCommandBinding } from "./postgresCommandStore.js";
+
+export { createPostgresStockWaitStore } from "./postgresStockWaitStore.js";
+export type { NativeStockWaitBinding, NativeStockWaitAdmission } from "./postgresStockWaitStore.js";
+
+/** Managed SQL is exposed for service-role hosts; no StockWaitStorePort or
+ * NewPurchaseStockReadPort TypeScript adapter is composed for this graph.
+ * SQL behavior is proved by the managed pgTAP/real-PostgreSQL witnesses.
+ */
+export const MANAGED_SUBSCRIPTION_STOCK_CAPABILITIES = Object.freeze({
+  graph: "managed",
+  stockRecovery: "unavailable",
+  stockWaitSurface: "sql",
+  stockAvailabilitySurface: "sql",
+  defaultEnabled: false,
+} as const);
+
+export { runRenewalBatchRows } from "./automaticRenewalExecution.js";
+export type { SubscriptionLifecycleFact } from "./contracts/messages.js";
+
+export { subscriptionLifecycleTemplate, createSubscriptionLifecycleMessages } from "./lifecycleMessages.js";
+export { createSubscriptionCommandExamples } from "./commandExamples.js";
+export { createSubscriptionServices } from "./services.js";

package/src/subscriptions/lifecycleMessages.ts

@@ -0,0 +1,37 @@
+import type { SubscriptionLifecycleMessageDescriptor, SubscriptionLifecycleMessagePort } from "./contracts/messages.js";
+
+/** Matches M5 and the existing M04 lifecycle templates. A mapping is not a send. */
+const templates: Readonly<Record<string, string>> = Object.freeze({
+  "subscription.created": "subscription-welcome",
+  "subscription.activation_action_required": "subscription-activation-action-required",
+  "subscription.cancelled": "subscription-cancelled",
+  "subscription.paused": "subscription-paused",
+  "subscription.resumed": "subscription-resumed",
+  "subscription.pause_reminder_due": "subscription-pause-reminder",
+  "subscription.delivery_rescheduled": "subscription-delivery-rescheduled",
+  "subscription.cycle_skipped": "subscription-cycle-skipped",
+  "subscription.address_changed": "subscription-address-changed",
+  "subscription.package_changed": "subscription-package-changed",
+  "subscription.renewal_upcoming": "subscription-renewal-upcoming",
+  "subscription_stock_wait.started": "subscription-stock-wait-started",
+  "subscription_stock_wait.resumed": "subscription-stock-wait-resumed",
+  payment_expired: "subscription-payment-expired",
+  payment_recovered: "subscription-payment-recovered", winback_eligible: "subscription-winback",
+  stock_wait_started: "subscription-stock-wait-started", stock_wait_resumed: "subscription-stock-wait-resumed",
+});
+export function subscriptionLifecycleTemplate(eventType: string, retryAttempt?: number | null): string | null {
+  // Installed dunning SQL uses rung 3 for every value other than exactly 1 or 2.
+  if (eventType === "payment_failed") return `subscription-payment-failed-${retryAttempt === 1 ? 1 : retryAttempt === 2 ? 2 : 3}`;
+  return Object.hasOwn(templates, eventType) ? templates[eventType]! : null;
+}
+/** M04 owns delivery, consent, rendering and durable replay. M10 never synthesizes a pause. */
+export function createSubscriptionLifecycleMessages(delivery: SubscriptionLifecycleMessagePort) {
+  return {
+    deliver(input: Omit<SubscriptionLifecycleMessageDescriptor, "templateSlug">) {
+      const templateSlug = subscriptionLifecycleTemplate(input.fact.kind, input.fact.kind === "payment_failed" ? input.fact.retryAttempt : null);
+      if (!templateSlug) throw new Error("subscription_lifecycle_message_unsupported");
+      if (input.messageKey !== input.fact.idempotencyKey) throw new Error("subscription_lifecycle_message_identity_mismatch");
+      return delivery.enqueue({ ...input, templateSlug });
+    },
+  };
+}

package/src/subscriptions/paymentOutcomes.ts

@@ -7,7 +7,7 @@ export async function readAndApplyProviderOutcome(deps: AutomaticRenewalRunDeps,
   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.status !== "succeeded" && observed.status !== "failed") 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");

package/src/subscriptions/postgresCommandStore.ts

@@ -0,0 +1,183 @@
+import type { SubscriptionCommand, SubscriptionCommandPort, SubscriptionCommandReceipt, SubscriptionCommandRefusal } from "./contracts/commands.js";
+import { subscriptionRecord, type SubscriptionQueryExecutor } from "./postgresRenewalStore.js";
+import { NATIVE_SUBSCRIPTION_CAPABILITIES } from "./index.js";
+
+export interface NativeSubscriptionCommand {
+  actorId: string; clientId: string; idempotencyKey: string; subscriptionId: string;
+  action: string; payload: Record<string, unknown>; now: string;
+}
+export interface NativeSubscriptionCommandBinding {
+  /** The callback must use one connection and commit/rollback the complete unit. */
+  withTransaction<T>(work: (executor: SubscriptionQueryExecutor) => Promise<T>): Promise<T>;
+  /** Validate address ownership and refuse address mutation; resolve SKUs and
+   * composition policy using trusted host evidence. No current-cycle write. */
+  futureTerms(command: Extract<SubscriptionCommand, { action: "edit_future_terms" }>): Promise<
+    | { coreLines: readonly { variantId: string; qty: number }[];
+        addonLines: readonly { variantId: string; qty: number }[]; compositionConstraint: Record<string, unknown> }
+    | SubscriptionCommandRefusal>;
+}
+
+const refusalCodes = new Set<SubscriptionCommandRefusal["reason"]>([
+  "multi_cycle_prepaid_unsupported",
+  "subscription_command_addon_not_found",
+  "subscription_command_bundle_total_mismatch",
+  "subscription_command_charge_timing_not_confirmed",
+  "subscription_command_idempotency_conflict",
+  "subscription_command_invalid_composition_constraint",
+  "subscription_command_invalid_input",
+  "subscription_command_not_active",
+  "subscription_command_operation_busy",
+  "subscription_command_pause_forbidden",
+  "subscription_command_payment_blocked",
+  "subscription_command_preview_unsupported",
+  "subscription_command_renewal_terms_missing",
+  "subscription_command_unsupported_action",
+  "subscription_edit_catalog_unavailable",
+  "subscription_edit_invalid_lines",
+  "subscription_edit_invalid_request",
+  "subscription_edit_quote_expired",
+  "subscription_edit_quote_required",
+  "subscription_edit_stale_template",
+  "subscription_edit_window_closed",
+  "subscription_lifecycle_invalid_transition",
+  "subscription_lifecycle_invalid_skip",
+  "subscription_lifecycle_invalid_slide",
+  "subscription_lifecycle_payment_blocked",
+]);
+function refusalReason(reason: unknown): SubscriptionCommandRefusal["reason"] {
+  return typeof reason === "string" && refusalCodes.has(reason as SubscriptionCommandRefusal["reason"])
+    ? reason as SubscriptionCommandRefusal["reason"] : "subscription_command_invalid_input";
+}
+function commandResult(result: Record<string, unknown>): Record<string, unknown> {
+  return result.status === "refused" || result.outcome === "refused"
+    ? { ...result, reason: refusalReason(result.reason) } : result;
+}
+
+/** N2 owns normalization, locking, quote acceptance, receipts and all writes.
+ * Preview is a separate persisted transaction; apply never executes payment. */
+export function createPostgresSubscriptionCommandStore(binding: Pick<NativeSubscriptionCommandBinding, "withTransaction">) {
+  return {
+    preview(input: NativeSubscriptionCommand) { return invokeCommand(binding, input, true); },
+    apply(input: NativeSubscriptionCommand) { return invokeCommand(binding, input, false); },
+  };
+}
+
+async function invokeCommand(binding: Pick<NativeSubscriptionCommandBinding, "withTransaction">,
+  input: NativeSubscriptionCommand, preview: boolean,
+  futureTerms?: () => ReturnType<NativeSubscriptionCommandBinding["futureTerms"]>): Promise<Record<string, unknown>> {
+  if (input.action === "multi_cycle_prepaid") return {
+    status: "refused", reason: NATIVE_SUBSCRIPTION_CAPABILITIES.multiCyclePrepaid.refusalCode,
+  };
+  return binding.withTransaction(async executor => {
+    const values = [input.actorId, input.clientId, input.idempotencyKey, input.subscriptionId, input.action, input.payload, input.now];
+    // Share N2's actor/key lock so a concurrent preview/apply cannot change
+    // the receipt between this read and native dispatch. Replay ends here,
+    // before any lifecycle function or other potentially writing call.
+    await executor.query("SELECT pg_advisory_xact_lock(hashtextextended($1::uuid::text||':'||$2::text,0))", [input.actorId, input.idempotencyKey]);
+    const stored = await executor.query(`WITH stored AS (
+      SELECT r.*, CASE WHEN $9::boolean THEN jsonb_set(r.command,'{payload}',
+        (r.command->'payload')-ARRAY['coreLines','addonLines','compositionConstraint']) ELSE r.command END AS requested_command
+      FROM public.subscription_command_receipts r WHERE r.actor_id=$1::uuid AND r.idempotency_key=$3::text
+        AND $7::timestamptz IS NOT NULL AND isfinite($7::timestamptz)
+        AND $3::text=btrim($3::text) AND char_length($3::text) BETWEEN 8 AND 180
+        AND $5::text IS NOT NULL AND jsonb_typeof($6::jsonb)='object'
+        AND (NOT $8::boolean OR NOT ($6::jsonb ? 'acceptedQuoteHash'))
+        AND EXISTS(SELECT 1 FROM public.subscriptions WHERE id=$4::uuid AND client_id=$2::uuid)
+    ), receipt AS (
+      SELECT *, CASE WHEN $8::boolean OR status='previewed' THEN
+        jsonb_set(requested_command,'{payload}',(requested_command->'payload')-'acceptedQuoteHash')=
+          jsonb_build_object('clientId',$2::uuid,'subscriptionId',$4::uuid,'action',$5::text,'payload',$6::jsonb-'acceptedQuoteHash')
+        ELSE requested_command=jsonb_build_object('clientId',$2::uuid,'subscriptionId',$4::uuid,'action',$5::text,'payload',$6::jsonb)
+        END AND ($8::boolean OR quote_hash IS NOT DISTINCT FROM ($6::jsonb->>'acceptedQuoteHash')) AS matches
+      FROM stored
+    ) SELECT command, CASE WHEN NOT matches THEN jsonb_build_object('status','refused','reason','subscription_command_idempotency_conflict')
+      WHEN $8::boolean OR status='refused' THEN result
+      WHEN status<>'previewed' THEN result||jsonb_build_object('status','replayed','originalStatus',status,'commandFingerprint',command_fingerprint)
+      END AS response FROM receipt`, [...values, preview, !!futureTerms]);
+    if (stored.rows[0]?.response) return commandResult(subscriptionRecord(stored.rows[0].response));
+    if (futureTerms) {
+      if (stored.rows[0]) {
+        // A matching preview already bound the host translation. Apply that
+        // exact quote even if the host's mutable policy has since changed.
+        values[5] = { ...subscriptionRecord(subscriptionRecord(stored.rows[0].command).payload),
+          acceptedQuoteHash: input.payload.acceptedQuoteHash };
+      } else {
+        const terms = await futureTerms();
+        if ("outcome" in terms) return commandResult({ ...terms });
+        values[5] = { ...input.payload, ...terms };
+      }
+    }
+    let result: Record<string, unknown> | undefined;
+    if (!preview && !Object.hasOwn(input.payload, "acceptedQuoteHash")) {
+      // N2 owns every command's no-op decision. Keep only its terminal noop;
+      // other direct applies must retain their quote requirement without
+      // persisting a speculative quote or refusal from this preview probe.
+      await executor.query("SAVEPOINT subscription_command_noop");
+      const { rows } = await executor.query("SELECT public.subscription_command_preview($1::uuid,$2::uuid,$3::text,$4::uuid,$5::text,$6::jsonb,$7::timestamptz) AS response", values);
+      const candidate = commandResult(subscriptionRecord(rows[0]?.response));
+      if (candidate.status === "noop") result = candidate;
+      else await executor.query("ROLLBACK TO SAVEPOINT subscription_command_noop");
+      await executor.query("RELEASE SAVEPOINT subscription_command_noop");
+    }
+    if (!result) {
+      const name = preview ? "subscription_command_preview" : "subscription_command_apply";
+      const { rows } = await executor.query(`SELECT public.${name}($1::uuid,$2::uuid,$3::text,$4::uuid,$5::text,$6::jsonb,$7::timestamptz) AS response`, values);
+      result = commandResult(subscriptionRecord(rows[0]?.response));
+    }
+    if (preview || result.status === "refused") return result;
+    const receipt = await executor.query(`SELECT command_fingerprint FROM public.subscription_command_receipts
+      WHERE actor_id=$1::uuid AND idempotency_key=$2::text`, [input.actorId, input.idempotencyKey]);
+    if (typeof receipt.rows[0]?.command_fingerprint !== "string") throw new Error("subscription_command_receipt_missing");
+    return { ...result, commandFingerprint: receipt.rows[0].command_fingerprint };
+  });
+}
+
+/** Trusted customer/operator authorization precedes this adapter. The native
+ * result's subscriptionStatus is the state recorded by the original execution,
+ * including on replay; it is not a fresh read of mutable subscription state. */
+export function createPostgresSubscriptionCommands(binding: NativeSubscriptionCommandBinding): SubscriptionCommandPort & {
+  preview(command: Extract<SubscriptionCommand, { action: "edit_future_terms" }>): Promise<Record<string, unknown> | SubscriptionCommandRefusal>;
+} {
+  function encode(command: SubscriptionCommand): NativeSubscriptionCommand | SubscriptionCommandRefusal {
+    // This serving adapter never pauses an active subscription. Existing native
+    // callers retain their separate, unchanged lifecycle contract.
+    if (command.action === "pause") return { outcome: "refused", reason: "subscription_command_pause_forbidden" };
+    const { actor, subscriptionId, idempotencyKey, now, action, ...fields } = command;
+    let payload: Record<string, unknown> = { ...fields, actorKind: actor.kind };
+    let nativeAction: string = action === "skip" ? "skip_next_cycle" : action === "slide" ? "slide_next_cycle" : action;
+    if (command.action === "edit_future_terms") {
+      // Preserve the host carriers as well as their native translation in the
+      // actual-command fingerprint. The accepted hash is stripped for preview.
+      payload = { ...payload, requestedCoreLines: command.coreLines, requestedAddonLines: command.addonLines,
+        compositionConstraintRef: command.compositionConstraint };
+      delete payload.coreLines;
+      delete payload.addonLines;
+      delete payload.compositionConstraint;
+      // An empty typed hash means no quote; preserve native no-op replay/probing.
+      if (command.acceptedQuoteHash === "") delete payload.acceptedQuoteHash;
+      nativeAction = "update_package_template";
+    }
+    return { actorId: actor.actorId, clientId: actor.clientId, subscriptionId, idempotencyKey, now, action: nativeAction, payload };
+  }
+  return {
+    capabilities: NATIVE_SUBSCRIPTION_CAPABILITIES,
+    async preview(command) {
+      const input = encode(command);
+      if ("outcome" in input) return input;
+      delete input.payload.acceptedQuoteHash;
+      return invokeCommand(binding, input, true, () => binding.futureTerms(command));
+    },
+    async apply(command) {
+      const input = encode(command);
+      if ("outcome" in input) return input;
+      const result = await invokeCommand(binding, input, false,
+        command.action === "edit_future_terms" ? () => binding.futureTerms(command) : undefined);
+      if (result.status === "refused" || result.outcome === "refused") return { outcome: "refused", reason: refusalReason(result.reason) };
+      if (result.status !== "applied" && result.status !== "replayed" && result.status !== "noop") throw new Error("subscription_command_response_invalid");
+      return { actorId: command.actor.actorId, idempotencyKey: command.idempotencyKey,
+        commandFingerprint: String(result.commandFingerprint), outcome: result.status, subscriptionId: String(result.subscriptionId),
+        originalState: String(result.subscriptionStatus), nextCycleAt: result.nextCycleAt == null ? null : String(result.nextCycleAt),
+        revision: String(result.templateVersion), eventId: result.eventId == null ? null : String(result.eventId) } satisfies SubscriptionCommandReceipt;
+    },
+  };
+}

package/src/subscriptions/postgresRetryStore.ts

@@ -56,6 +56,17 @@ export function createPostgresRetryStore(executor: SubscriptionQueryExecutor) {
     async applyFailure(operationId: string, key: string, input: NativeRetryFailure) {
       return row(await invoke("subscription_retry_apply_failure", [operationId, key, input]));
     },
+    /** Read the immutable rung receipt against the current case. An interrupted
+     * apply still needs propagation; an already advanced case must not be rewritten. */
+    async failureProgress(operationId: string, key: string): Promise<{ replayed: boolean; caseAdvanced: boolean }> {
+      const result = await executor.query(`SELECT true AS replayed,
+        (c.retry_attempt >= (r.result->>'retry_attempt')::integer OR o.state='recovered') AS case_advanced
+        FROM public.subscription_retry_obligations o
+        JOIN public.subscription_retry_receipts r ON r.obligation_id=o.id AND r.kind='failure' AND r.receipt_key=$2::text
+        LEFT JOIN public.subscription_dunning_cases c ON c.id=o.case_id
+        WHERE o.renewal_operation_id=$1::uuid`, [operationId, key]);
+      return { replayed: result.rows.length === 1, caseAdvanced: result.rows[0]?.case_advanced === true };
+    },
     async openCase(operationId: string, template: string, recoveryPath: string | null) {
       return subscriptionRecord(await invoke("subscription_retry_open_case", [operationId, template, recoveryPath]));
     },