@openlup/platform 0.23.0 → 0.25.0

package/src/invoicing/snapshot.ts

@@ -0,0 +1,192 @@
+import type { InvoiceBuyer } from "./contracts/facts.js";
+import { mapCanonicalIssueLines } from "./accountingCanonicalProviderLines.js";
+import { allocateChargedGrossTotals } from "./accountingLineAllocation.js";
+
+type IssueLines = ReturnType<typeof mapCanonicalIssueLines>;
+interface Options {
+  defaultLineLabel: string;
+  deliveryLabel: string;
+  defaultTaxRate: string;
+}
+/** Compatibility projection of a claimed host snapshot, not a second store contract.
+ * Seller/date/kind/payment selection remains with the host; no environment is read.
+ */
+export function mapInvoiceClaimToProviderSnapshot<Seller, Kind, Payment>(input: {
+  orderRef: string;
+  issueDate: string;
+  sellDate: string;
+  currency: string;
+  seller: Seller;
+  buyerSnapshot: Record<string, unknown>;
+  documentKind: Kind;
+  governmentClearanceRequired: boolean;
+  payment: Payment;
+  linesSnapshot: unknown[];
+  totalGrossMinor: number;
+  totalNetMinor: number;
+  orderMoney: unknown;
+}, options: Options & { defaultBuyerLabel: string }) {
+  return {
+    orderRef: input.orderRef,
+    issueDate: input.issueDate,
+    sellDate: input.sellDate,
+    currency: input.currency,
+    seller: input.seller,
+    buyer: {
+      name: textValue(input.buyerSnapshot.name) ?? options.defaultBuyerLabel,
+      email: textValue(input.buyerSnapshot.email),
+      taxId: textValue(input.buyerSnapshot.taxId),
+      companyName: textValue(input.buyerSnapshot.companyName),
+      address: mapBuyerAddress(input.buyerSnapshot.address),
+    },
+    documentKind: input.documentKind,
+    governmentClearanceRequired: input.governmentClearanceRequired,
+    payment: input.payment,
+    lines: mapIssueLinesToChargedTotal(input.linesSnapshot, input.totalGrossMinor, input.totalNetMinor, input.orderMoney, options),
+    chargedTotalGrossMinor: input.totalGrossMinor,
+  };
+}
+
+// Canonical issue snapshots already carry effective item and explicit delivery
+// positions and are verified as a zero-delta passthrough. Historical snapshots
+// without positionKind retain the independent #1693 reconciliation below.
+function mapIssueLinesToChargedTotal(
+  linesSnapshot: unknown[],
+  chargedTotalGrossMinor: number,
+  chargedTotalNetMinor: number,
+  orderMoney: unknown,
+  options: Options,
+): IssueLines {
+  const canonicalKinds = linesSnapshot.map((line) => textValue(isRecord(line) ? line.positionKind : null));
+  if (canonicalKinds.some(Boolean)) {
+    if (!canonicalKinds.every((kind) => kind === "item" || kind === "delivery")) {
+      throw new Error("accounting_invoice_canonical_positions_mixed_or_invalid");
+    }
+    return mapCanonicalIssueLines(
+      linesSnapshot,
+      chargedTotalGrossMinor,
+      chargedTotalNetMinor,
+      options.defaultLineLabel,
+    );
+  }
+
+  const parsed = linesSnapshot.map((line) => parseLineSnapshot(line, options));
+  const deliveryGrossMinor = readDeliveryGrossMinor(orderMoney, chargedTotalGrossMinor);
+  const chargedTotals = allocateChargedGrossTotals(
+    parsed.map((line) => line.totalGrossMinor),
+    chargedTotalGrossMinor - deliveryGrossMinor,
+  );
+  const positions: IssueLines = parsed.map((line, index) => {
+    const totalGrossMinor = chargedTotals[index];
+    const totalNetMinor = estimateNetMinor(totalGrossMinor, line.vatRate);
+    return {
+      name: line.name,
+      quantity: line.quantity,
+      unitGrossMinor: Math.round(totalGrossMinor / line.quantity),
+      unitNetMinor: Math.round(totalNetMinor / line.quantity),
+      totalGrossMinor,
+      totalNetMinor,
+      vatRate: line.vatRate,
+    };
+  });
+  if (deliveryGrossMinor > 0) {
+    positions.push(buildDeliveryPosition(deliveryGrossMinor, parsed, options));
+  }
+  return positions;
+}
+
+// Legacy-only compatibility: pre-canonical claims had no explicit delivery
+// position, so their effective delivery is the closed header residual. Current
+// canonical claims never enter this path and use persisted shipping columns.
+// Every inconsistent legacy shape degrades to 0 and then fails closed if the
+// catalog lines cannot reconcile to the charged header.
+function readDeliveryGrossMinor(orderMoney: unknown, chargedTotalGrossMinor: number): number {
+  if (!isRecord(orderMoney)) return 0;
+  const subtotal = numberValue(orderMoney.subtotalCents);
+  const discount = numberValue(orderMoney.discountCents);
+  const total = numberValue(orderMoney.totalCents);
+  if (subtotal === null || discount === null || total === null) return 0;
+  if (![subtotal, discount, total].every((value) => Number.isInteger(value) && value >= 0)) return 0;
+  if (discount > subtotal) return 0;
+  if (total !== chargedTotalGrossMinor) return 0;
+  const deliveryGrossMinor = chargedTotalGrossMinor - (subtotal - discount);
+  return deliveryGrossMinor > 0 ? deliveryGrossMinor : 0;
+}
+
+// Delivery is an ancillary supply and follows the goods' VAT rate; with mixed
+// item rates (or no item line to source a rate from) the correct rate is
+// ambiguous, so the claim fails closed into the outbox last_error.
+function buildDeliveryPosition(
+  deliveryGrossMinor: number,
+  itemLines: Array<{ vatRate: string }>,
+  options: Options,
+): IssueLines[number] {
+  const rates = [...new Set(itemLines.map((line) => line.vatRate.trim()))];
+  if (rates.length === 0) {
+    throw new Error(`accounting_invoice_delivery_vat_rate_unavailable delivery=${deliveryGrossMinor}`);
+  }
+  if (rates.length > 1) {
+    throw new Error(`accounting_invoice_delivery_vat_rates_mixed rates=${rates.join(",")}`);
+  }
+  const vatRate = rates[0];
+  const totalNetMinor = estimateNetMinor(deliveryGrossMinor, vatRate);
+  return {
+    name: options.deliveryLabel,
+    quantity: 1,
+    unitGrossMinor: deliveryGrossMinor,
+    unitNetMinor: totalNetMinor,
+    totalGrossMinor: deliveryGrossMinor,
+    totalNetMinor,
+    vatRate,
+  };
+}
+
+function mapBuyerAddress(value: unknown): NonNullable<InvoiceBuyer["address"]> {
+  const address = isRecord(value) ? value : {};
+  return {
+    line1: textValue(address.line1),
+    postalCode: textValue(address.postalCode),
+    city: textValue(address.city),
+    country: textValue(address.country),
+  };
+}
+
+function parseLineSnapshot(value: unknown, options: Options): {
+  name: string;
+  quantity: number;
+  totalGrossMinor: number;
+  vatRate: string;
+} {
+  const row = isRecord(value) ? value : {};
+  const quantity = numberValue(row.quantity) || 1;
+  const vatRate = textValue(row.vatRate) ?? options.defaultTaxRate;
+  // Legacy (pre-#1693) lines_snapshot rows carry only the per-unit
+  // unitGrossMinor, so the line total is unit price times quantity.
+  const unitGrossMinor = numberValue(row.unitGrossMinor);
+  const totalGrossMinor = numberValue(row.totalGrossMinor) ??
+    (unitGrossMinor === null ? 0 : unitGrossMinor * quantity);
+  return {
+    name: textValue(row.name) ?? options.defaultLineLabel,
+    quantity,
+    totalGrossMinor,
+    vatRate,
+  };
+}
+
+function estimateNetMinor(grossMinor: number, vatRate: string): number {
+  const rate = Number(vatRate.replace(",", "."));
+  return Number.isFinite(rate) ? Math.round(grossMinor / (1 + rate / 100)) : grossMinor;
+}
+
+function textValue(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function numberValue(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

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