@openlup/platform 0.22.0 → 0.24.0

package/src/invoicing/readModel.ts

@@ -0,0 +1,80 @@
+import type { InvoiceHostPorts, InvoiceIdentity, InvoiceProviderPort, InvoiceStorePort } from "./contracts/index.js";
+import { assertInvoicePdf } from "./artifacts.js";
+import { opaqueReference, readInvoiceReadback } from "./readback.js";
+
+const unsupported = () => ({ kind: "unsupported", code: "host_binding_required", retryable: false, effectMayHaveSucceeded: false } as const);
+const unknown = () => ({ kind: "unknown", code: "unknown" } as const);
+
+/** Read-only orchestration. Auth, owner resolution and queries stay in host
+ * callbacks. Safe native account projections preserve negative correction totals,
+ * currency and parent identity without exposing provider payloads or URLs.
+ * @consumer Customer download/history and authorized operator host facades.
+ */
+export function createInvoiceReadModel(ports: {
+  accountHistory?: InvoiceHostPorts["accountHistory"];
+  artifacts?: Pick<InvoiceHostPorts["artifacts"], "download">;
+  provider?: Pick<InvoiceProviderPort, "read">;
+  duties?: Pick<InvoiceStorePort, "readDuties">;
+} = {}) {
+  return {
+    async history(input: Parameters<InvoiceHostPorts["accountHistory"]["read"]>[0]): ReturnType<InvoiceHostPorts["accountHistory"]["read"]> {
+      if (!ports.accountHistory) return unsupported();
+      try {
+        const result = await ports.accountHistory.read(input);
+        if (result.kind !== "found") return result.kind === "unsupported" ? unsupported() : result.kind === "denied" ? { kind: "denied" } : unknown();
+        if (result.accountRef !== input.accountRef || result.orderId !== input.orderId) return { kind: "denied" };
+        return {
+          kind: "found", accountRef: input.accountRef, orderId: input.orderId,
+          documents: result.documents.map(document => ({
+            documentRef: document.documentRef, invoiceRef: document.invoiceRef,
+            parentDocumentRef: document.parentDocumentRef, role: document.role,
+            status: document.status, issuedAt: document.issuedAt,
+            clearance: document.clearance ? { state: document.clearance.state, reference: document.clearance.reference } : null,
+            documentKind: document.documentKind, artifact: document.artifact,
+            providerDocumentNumber: document.providerDocumentNumber,
+            totalGrossMinor: document.totalGrossMinor, currency: document.currency,
+            emailState: document.emailState, isCurrent: document.isCurrent,
+            createdAt: document.createdAt, downloadAvailable: document.downloadAvailable,
+          })),
+        };
+      } catch { return unknown(); }
+    },
+    async download(input: Parameters<InvoiceHostPorts["accountHistory"]["resolveDownload"]>[0]) {
+      if (!ports.accountHistory || !ports.artifacts) return unsupported();
+      try {
+        const ticket = await ports.accountHistory.resolveDownload(input);
+        if (ticket.kind !== "authorized") return ticket.kind === "unsupported" ? unsupported() : ticket.kind === "denied" ? { kind: "denied" as const } : unknown();
+        if (ticket.identity.documentRef !== input.documentRef || !opaqueReference(ticket.artifactRef)) return { kind: "denied" as const };
+        const pdf = await ports.artifacts.download({ identity: ticket.identity, artifactRef: ticket.artifactRef });
+        if (pdf.kind !== "downloaded") return pdf.kind === "unsupported" ? unsupported() : unknown();
+        assertInvoicePdf(pdf);
+        return { kind: "downloaded" as const, content: pdf.content, contentType: pdf.contentType, fileName: ticket.fileName, parentDocumentRef: ticket.parentDocumentRef };
+      } catch { return unknown(); }
+    },
+    async readback(identity: InvoiceIdentity) {
+      return ports.provider ? readInvoiceReadback(ports.provider, identity) : unsupported();
+    },
+    /** Operator-only duty readback. The host must authorize the caller before
+     * invoking it, as operator() does; this method has no auth hook of its own. */
+    async readDuties(orderId: string) {
+      if (!ports.duties) return unsupported();
+      try { return await ports.duties.readDuties(orderId); } catch { return unknown(); }
+    },
+    /** The authorize callback runs before the query. HTTP status mapping stays host-owned. */
+    async operator<Summary>(input: { authorize(): Promise<boolean>; read(): Promise<Summary> }) {
+      if (!await input.authorize()) return { kind: "denied" as const };
+      return { kind: "found" as const, value: await input.read() };
+    },
+    /** Legacy ticket resolver verifies the real order owner before any PDF I/O. */
+    async ownedPdf<Ticket, Pdf extends { content: Uint8Array; contentType: string }>(input: {
+      resolve(): Promise<Ticket | null>;
+      download(ticket: Ticket): Promise<Pdf>;
+    }) {
+      const ticket = await input.resolve();
+      if (!ticket) return { kind: "denied" as const };
+      const pdf = await input.download(ticket);
+      assertInvoicePdf(pdf);
+      return { kind: "downloaded" as const, ticket, pdf };
+    },
+  };
+}

package/src/invoicing/readback.ts

@@ -0,0 +1,26 @@
+import type { InvoiceIdentity, InvoiceProviderPort, InvoiceReadbackResult } from "./contracts/provider.js";
+
+const identityKeys = ["providerRef", "requestKey", "providerCreateIdentity", "factRevision", "orderRef", "invoiceRef", "operation", "correctionRef", "parentProviderDocumentRef"] as const;
+/** Internal validation used by the read model. No nullable lookup shortcut. */
+export async function readInvoiceReadback(provider: Pick<InvoiceProviderPort, "read">, identity: InvoiceIdentity): Promise<InvoiceReadbackResult> {
+  const unknown = (): InvoiceReadbackResult => ({ kind: "unknown", identity, code: "unknown" });
+  try {
+    const result = await provider.read(identity);
+    if (result.kind === "unsupported") return { kind: "unsupported", code: result.code, retryable: false, effectMayHaveSucceeded: false };
+    if (!sameIdentity(identity, result.identity)) return unknown();
+    if (result.kind === "found") {
+      if (!opaqueReference(result.providerDocumentRef)) return unknown();
+      return { kind: "found", identity, providerDocumentRef: result.providerDocumentRef, providerDocumentNumber: result.providerDocumentNumber, proof: { evidenceRef: result.proof.evidenceRef, fingerprint: result.proof.fingerprint, observedAt: result.proof.observedAt } };
+    }
+    if (result.kind === "absent" && result.evidence.exact === true && result.evidence.complete === true && sameIdentity(identity, result.evidence.scope)) {
+      return { kind: "absent", identity, evidence: { evidenceRef: result.evidence.evidenceRef, fingerprint: result.evidence.fingerprint, observedAt: result.evidence.observedAt, exact: true, complete: true, scope: identity } };
+    }
+    return unknown();
+  } catch { return unknown(); }
+}
+function sameIdentity(a: InvoiceIdentity, b: InvoiceIdentity): boolean {
+  return Boolean(b) && identityKeys.every(key => a[key] === b[key]);
+}
+export function opaqueReference(ref: string): boolean {
+  return typeof ref === "string" && ref.trim().length > 0 && !/^(?:https?:|data:|blob:|\/\/)/i.test(ref.trim());
+}

package/src/invoicing/reversal.ts

@@ -0,0 +1,34 @@
+/** Donor reversal outcome/order semantics over host event adapters and writer.
+ * @consumer api/_cron/accountingOrderReversalHandlers.ts
+ */
+export function createInvoiceReversalHandlers<Row, Request, Result extends { action: string; invoice: { status: string } | null }>(input: {
+  enabled: boolean;
+  events: readonly { eventType: string; adapt(row: Row): { kind: "ready"; request: Request } | { kind: "invalid_payload" } }[];
+  request(request: Request): Promise<Result>;
+}) {
+  if (!input.enabled) return [];
+  return input.events.map(event => ({
+    eventType: event.eventType,
+    timeoutMs: 10_000,
+    async handle(row: Row): Promise<
+      | { kind: "discard"; reason: string }
+      | { kind: "processed"; detail: { accountingReversalAction: string; invoiceStatus: string } }
+      | { kind: "retry"; reason: string }
+    > {
+      const compatibility = event.adapt(row);
+      if (compatibility.kind === "invalid_payload") {
+        return { kind: "discard", reason: "accounting_reversal_payload_invalid" };
+      }
+      try {
+        const result = await input.request(compatibility.request);
+        return {
+          kind: "processed",
+          detail: { accountingReversalAction: result.action, invoiceStatus: result.invoice?.status ?? "no_invoice" },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { kind: "retry", reason: message.slice(0, 300) };
+      }
+    },
+  }));
+}

package/src/invoicing/sellerRevision.ts

@@ -0,0 +1,20 @@
+import type { InvoiceSellerRevision } from "./contracts/facts.js";
+import type { InvoiceUnsupported } from "./contracts/provider.js";
+
+/** Read the host selection before leasing. Persistence and race serialization
+ * belong exclusively to the pinned SQL wrapper, never to an in-memory cache.
+ * Unknown/unsupported selection consumes no claim and must be retried by the host.
+ */
+export async function claimInvoiceSellerRevision<Seller extends object>(read: () => Promise<
+  | ({ readonly kind: "found" } & InvoiceSellerRevision<Seller>)
+  | { readonly kind: "unknown"; readonly code: "unknown" }
+  | InvoiceUnsupported
+>) {
+  const selected = await read();
+  if (selected.kind !== "found") return selected;
+  if (!selected.seller || typeof selected.seller !== "object" || Array.isArray(selected.seller)
+    || typeof selected.revisionRef !== "string" || !selected.revisionRef.trim()) {
+    return { kind: "unsupported", code: "host_binding_required", retryable: false, effectMayHaveSucceeded: false } as const;
+  }
+  return { kind: "found", seller: selected.seller, revisionRef: selected.revisionRef } as const;
+}

package/src/invoicing/settlementSync.ts

@@ -0,0 +1,37 @@
+import type { InvoiceSettlementPort, InvoiceSettlementItem } from "./contracts/settlement.js";
+
+/** Preserve each immutable balance item, nullable links and original host key.
+ * Transport, resolution and richer durable item storage remain host-owned.
+ * Legacy batch/payment receipts may collapse items: later reuse is returned as
+ * identity_mismatch without another write; processing continues. Only an item-capable
+ * recorder can produce distinct recorded receipts. This records bank evidence only and has no payment-success writer.
+ */
+export async function syncInvoicePayoutSettlements<Item>(input: {
+  list(limit: number): Promise<readonly Item[]>;
+  project(item: Item): InvoiceSettlementItem | Promise<InvoiceSettlementItem>;
+  settlement: Pick<InvoiceSettlementPort, "record">;
+  limit?: number;
+}) {
+  const items = await input.list(input.limit ?? 10);
+  const result = { checked: items.length, recorded: 0, replayed: 0, items: [] as Awaited<ReturnType<InvoiceSettlementPort["record"]>>[] };
+  const receipts = new Map<string, string>();
+  for (const item of items) {
+    const evidence = await input.project(item);
+    const write = await input.settlement.record(evidence);
+    if (write.kind !== "recorded" || write.itemRef !== evidence.itemRef) {
+      // Unknown/conflict/unsupported are never counted as accepted evidence.
+      throw new Error(write.kind === "conflict" ? write.code : write.kind === "unknown" ? "unknown" : "unsupported");
+    }
+    const scope = JSON.stringify([evidence.providerRef, evidence.batchRef, evidence.itemRef, evidence.providerPaymentRef]);
+    const previous = receipts.get(write.settlementItemRef);
+    if (previous !== undefined && previous !== scope) {
+      result.items.push({ kind: "conflict", itemRef: evidence.itemRef, code: "identity_mismatch" });
+      continue;
+    }
+    receipts.set(write.settlementItemRef, scope);
+    result.items.push(write);
+    if (write.replayed) result.replayed += 1;
+    else result.recorded += 1;
+  }
+  return result;
+}

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/automaticRenewal.ts

@@ -0,0 +1,87 @@
+import type { RenewalDue, RenewalExecutionRequest, RenewalFrozenSnapshot, RenewalPaymentRail, RenewalPreparedSettlement, RenewalReadback, RenewalReservationResult, RenewalSettlementPort, RenewalStorePort } from "./contracts/renewal.js";
+import type { RenewalFailureHandoffPort } from "./contracts/dunning.js";
+import { automaticRenewalResult, handoffRefusal, recoverPreparedExternalAttempt, refuseRenewalBeforePayment, runRenewalBatchRows } from "./automaticRenewalExecution.js";
+import { readAndApplyProviderOutcome } from "./paymentOutcomes.js";
+export type AutomaticRenewalRunStatus = "succeeded" | "refused" | "deferred" | "awaiting_provider" | "error" | "lease_active" | "terminal_replay";
+export interface AutomaticRenewalRunResult {
+  subscriptionId: string; identityKey: string; operationId: string;
+  status: AutomaticRenewalRunStatus; replayed: boolean; reason: string | null; caseRef?: string;
+}
+export interface AutomaticRenewalPolicy {
+  executionInput(due: RenewalDue, operation: RenewalReadback, prepared: Pick<RenewalPreparedSettlement, "orderId" | "settlementIntentId">): RenewalExecutionRequest;
+  validateInput(input: RenewalExecutionRequest): void;
+  classifyFailure(reason: string): string;
+  identityKey(due: RenewalDue): string;
+}
+export interface AutomaticRenewalRunDeps {
+  store: RenewalStorePort;
+  inventory: {
+    expireReservations(input: { now: string; limit?: number }): Promise<number>;
+    reserve(input: { operationId: string; claimToken: string; now: string }): Promise<RenewalReservationResult>;
+  };
+  settlement: RenewalSettlementPort;
+  paymentRails: { resolve(channelKey: string): RenewalPaymentRail | null };
+  failureHandoff: RenewalFailureHandoffPort;
+  policy: AutomaticRenewalPolicy;
+  workerId: string; now?: () => string;
+}
+export async function runAutomaticSubscriptionRenewals(deps: AutomaticRenewalRunDeps, limit = 50): Promise<AutomaticRenewalRunResult[]> {
+  const now = (deps.now ?? defaultNow)();
+  await deps.inventory.expireReservations({ now, limit: Math.max(limit, 100) });
+  const due = await deps.store.listDue(limit, now);
+  return runRenewalBatchRows(due, row => runOneAutomaticSubscriptionRenewal(deps, row, now), deps.policy);
+}
+export async function runOneAutomaticSubscriptionRenewal(deps: AutomaticRenewalRunDeps, due: RenewalDue, occurredAt = (deps.now ?? defaultNow)()): Promise<AutomaticRenewalRunResult> {
+  const schedule = { subscriptionId: due.subscriptionId, scheduledAt: due.scheduledAt, scheduledInstant: due.scheduledInstant };
+  const snapshot = await deps.store.buildCycleSnapshots(schedule);
+  const claim = await deps.store.claimDue({ snapshot, workerId: deps.workerId, now: occurredAt });
+  if (claim.state === "succeeded" || claim.state === "refused") return automaticRenewalResult(claim, "terminal_replay", claim.terminalReason);
+  if (!claim.acquired) return automaticRenewalResult(claim, "lease_active", claim.reason);
+  const rail = deps.paymentRails.resolve(snapshot.settlementChannelKey);
+  if (!rail) return refuseRenewalBeforePayment({ store: deps.store, operation: claim, reason: "settlement_channel_not_configured", occurredAt });
+  if (claim.state === "attempt_prepared") return resumePreparedAttempt(deps, claim, rail, occurredAt);
+  const mandate = await deps.store.readMandateEvidence(schedule);
+  if (!mandate.authorized || mandate.authorizationRef !== snapshot.authorizationRef) return refuseRenewalBeforePayment({ store: deps.store, operation: claim, reason: "authorization_evidence_mismatch", occurredAt });
+  const delivery = await deps.store.admitDeliveryAlignment({ ...schedule, occurredAt });
+  if (!delivery.allowed) {
+    if (delivery.deferred) return { ...automaticRenewalResult(claim, "deferred", delivery.reason), ...(delivery.caseRef ? { caseRef: delivery.caseRef } : {}) };
+    return refuseRenewalBeforePayment({ store: deps.store, operation: claim, reason: delivery.reason, occurredAt });
+  }
+  const reservation = await deps.inventory.reserve({ operationId: claim.operationId, claimToken: claim.claimToken, now: occurredAt });
+  if (!reservation.reserved) return automaticRenewalResult(claim, "refused", reservation.reason ?? "insufficient_atp");
+  const prepared = await deps.settlement.prepareRenewal({ operationId: claim.operationId, claimToken: claim.claimToken, now: occurredAt });
+  if (prepared.replayed) {
+    const readback = await deps.store.readRenewal(claim.identityKey);
+    if (!readback) throw new Error("subscription_renewal_prepared_readback_missing");
+    return resumePreparedAttempt(deps, readback, rail, occurredAt);
+  }
+  const executionInput = deps.policy.executionInput(due, claim, prepared);
+  try { deps.policy.validateInput(executionInput); }
+  catch {
+    await deps.settlement.recordTerminalOutcome({ operationId: claim.operationId, eventKey: `${claim.identityKey}:provider-preflight`, operationFingerprint: claim.operationFingerprint, outcome: "refused", reason: "provider_input_invalid", occurredAt });
+    return automaticRenewalResult(claim, "refused", "provider_input_invalid");
+  }
+  let execution: Awaited<ReturnType<RenewalPaymentRail["execute"]>>;
+  try { execution = await rail.execute(executionInput); }
+  catch { return automaticRenewalResult(claim, "awaiting_provider", "provider_execution_indeterminate"); }
+  const externalAttemptRef = execution.externalAttemptRef?.trim() || null;
+  if (externalAttemptRef) await deps.settlement.acknowledgeExternalAttempt({ operationId: claim.operationId, operationFingerprint: claim.operationFingerprint, externalAttemptRef, acknowledgedAt: occurredAt });
+  if (execution.failure || execution.status === "requires_action") {
+    const reason = execution.failure?.reason ?? (execution.status === "requires_action" ? "off_session_sca_required" : "provider_failed");
+    return handoffRefusal(deps, claim, prepared, externalAttemptRef, reason, execution.failure?.failureClass ?? deps.policy.classifyFailure(reason), occurredAt);
+  }
+  if (!externalAttemptRef) return automaticRenewalResult(claim, "awaiting_provider", "provider_attempt_ack_missing");
+  return readAndApplyProviderOutcome(deps, claim, prepared, rail, externalAttemptRef, occurredAt);
+}
+async function resumePreparedAttempt(deps: AutomaticRenewalRunDeps, operation: RenewalReadback, rail: RenewalPaymentRail, occurredAt: string): Promise<AutomaticRenewalRunResult> {
+  if (!operation.cycleId || !operation.orderId || !operation.settlementIntentId) throw new Error("subscription_renewal_prepared_artifacts_missing");
+  const externalAttemptRef = await recoverPreparedExternalAttempt({ operation, rail, settlement: deps.settlement, occurredAt });
+  if (!externalAttemptRef) return automaticRenewalResult(operation, "awaiting_provider", "prepared_attempt_ack_missing");
+  return readAndApplyProviderOutcome(deps, operation, { cycleId: operation.cycleId, orderId: operation.orderId, settlementIntentId: operation.settlementIntentId }, rail, externalAttemptRef, occurredAt);
+}
+function defaultNow(): string { return new Date().toISOString(); }
+/** No implicit +1: ambiguous history must be resolved by the host before opening a repair case. */
+export function correlatedLogicalCycle(snapshot: RenewalFrozenSnapshot): number {
+  if (snapshot.cycle.status !== "correlated") throw new Error("subscription_renewal_cycle_correlation_required");
+  return snapshot.cycle.logicalCycleNumber;
+}

package/src/subscriptions/automaticRenewalExecution.ts

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

package/src/subscriptions/contracts/commands.ts

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

package/src/subscriptions/contracts/dunning.ts

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

package/src/subscriptions/contracts/index.ts

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