@openlup/core 0.6.0 → 0.9.0

package/CHANGELOG.md

@@ -16,6 +16,30 @@ SemVer promise.
 
 ### Changed
 
+- **BEHAVIOUR CHANGE for the subscription status matrix.** `cancelled` is no
+  longer terminal: `cancelled -> active` is now an allowed edge. This is the
+  owner win-back that the managed SQL guard
+  `public.subscription_guard_status_transition` already admits. Only the new
+  `reactivateSubscription` takes that edge. `resumeSubscription` still leaves
+  `paused` only and still refuses a cancelled subscription. `completed` stays
+  terminal. A caller that treated `cancelled` as final must now expect a
+  reactivated subscription to renew again.
+- **BEHAVIOUR CHANGE: an exhausted retry ladder now has a modelled outcome.** A
+  renewal whose refusals ran past the last rung may pause an active
+  subscription through `pauseSubscriptionForExpiredDunning`, which is the
+  sanctioned non-payment rule. It is the only engine path that suspends a live
+  subscription for a reason the owner did not choose. A ladder cut short by a
+  terminating refusal class, or a failure that still has a retry after it, is
+  refused as `dunning_not_exhausted` and leaves the subscription active.
+  `recordPaymentFailure` is unchanged and still never touches the subscription.
+- `SubscriptionEngineErrorCode` gains `missing_payment_method` and
+  `dunning_not_exhausted`. An exhaustive `switch` over the union must handle
+  both.
+
+- Publishable on the npm `preview` dist-tag as `0.9.0`, for source preview
+  `openlup-source-preview/9`.
+- Publishable on the npm `preview` dist-tag as `0.7.0`, for source preview
+  `openlup-source-preview/7`.
 - Publishable on the npm `preview` dist-tag as `0.6.0`, for source preview
   `openlup-source-preview/6`. Directory `npm publish` stays refused.
 
@@ -37,6 +61,25 @@ SemVer promise.
 
 ### Added
 
+- Export neutral lookup normalization from `./company-identity` for extensions.
+
+- `SUBSCRIPTION_STATUS_TRANSITIONS`, the frozen status matrix, and
+  `canTransitionSubscriptionStatus` on `./subscription`. The matrix mirrors the
+  managed SQL guard over the engine's four statuses, and a contract test
+  enumerates every ordered pair.
+- `reactivateSubscription`, the win-back from `cancelled`. It needs a stored
+  payment method and restarts the schedule `RESTART_LEAD_DAYS` (two) days out,
+  never earlier than the stored `nextCycleAt`.
+- `isDunningLadderExhausted(cycle, cadence?)` on the retry ladder. It holds when
+  a cycle is `payment_failed`, has nothing scheduled, and its attempt is past
+  `maxRetryAttempts(cadence)`.
+- `pauseSubscriptionForExpiredDunning` and
+  `resumeSubscriptionFromExpiredDunning`. The resume is the customer's recovery
+  from the non-payment pause: it takes an optional replacement method, skips the
+  uncollected cycle, and restarts the schedule like a win-back.
+- `recordPaymentFailure` takes an optional `cadence`, so a deployment ladder
+  reaches the schedule and the exhaustion check alike. Callers that pass none
+  keep the shipped ladder.
 - `recordPaymentFailure` accepts an optional neutral `failureClass` and passes it
   to the canonical retry-ladder decision. Existing callers remain
   source-compatible. The shipped terminating-class set is exactly

package/README.md

@@ -58,9 +58,30 @@ Focused proofs are `npm run api:check`, `npm run release:check`, and
 `npm run test:consumer`. The root test script skips this suite. A `preview`
 install is evaluation, not a supported install.
 
+Repository neutrality checks reuse the existing source scanner through
+[the tree counting interface](./scripts/neutrality-tree-counts.ts). This
+process interface reads JSON containing source paths, contents and a policy
+from standard input, then emits finding counts for each path. Shell sources
+retain the scanner's existing shell handling. The interface adds no package
+export and changes no matcher or kernel behavior.
+
+The repository checker also calls the UI neutrality counting process with
+`--counts-json` to count its existing patterns over the supplied sources. Running that checker without
+arguments still scans the UI source directory and refuses any forbidden hit.
+Published Tree CI runs the repository ratchet in required `self-check` and its
+CLI refusal tests separately in required `test`; unrestricted root diagnostics
+do not replace either gate. The independent core CI step retains this package's
+complete verification when root diagnostics are red.
+
+Together these interfaces let the repository measure existing findings without
+making one package import another package's internals. They provide source
+neutrality evidence, not package activation or consumer compatibility evidence.
+
 ## Kernel Documentation
 
 - [`docs/SUBSCRIPTION_ENGINE.md`](docs/SUBSCRIPTION_ENGINE.md) — what the
   `./subscription` kernel owns, its deterministic-clock contract, the
   late-payment cycle-shift rule and its monotonic clamp, and how a host
   application consumes it.
+
+<!-- openlup-doc-impact {"unit":"core","digest":"sha256-c190852df0084211fd02f2d72c4abeaacfa238d45e0a86eaa30ae456cb8bb830","reason":"The core manifest and its lockfile change only the lockstep version from 0.7.0 to 0.9.0. Exports, package smoke, publication settings and the development-preview maturity described here are unchanged."} -->

package/dist/company-identity/contracts.d.ts

@@ -96,11 +96,9 @@ export declare const companyIdentitySourceSchema: z.ZodObject<{
     observedAt: z.ZodString;
     evidenceHash: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
-/** A lookup request. `country` is an open ISO-3166 alpha-2 code (not restricted
- * to any single country); `identifierKind`/`identifierValue` name and carry the
- * tax/registry id; `manualCompany` optionally seeds user-entered data an adapter
- * may reconcile against a registry. Parsing normalizes country to upper-case and
- * identifier kind to lower-case. */
+/** Lookup coordinates with optional manual identity for registry reconciliation.
+ * Country is an open ISO-3166 alpha-2 code. Parsing uppercases country and
+ * lowercases identifier kind; national tax-id rules belong to extensions. */
 /** @beta */
 export declare const companyIdentityLookupRequestSchema: z.ZodPipe<z.ZodObject<{
     country: z.ZodString;
@@ -212,6 +210,8 @@ interface NormalizableCompanyIdentityLookupRequest {
     purpose: CompanyIdentityPurpose;
     manualCompany?: Partial<CompanyIdentityCompany>;
 }
+/** @beta */
+export declare function normalizeCompanyIdentityLookupRequest(request: NormalizableCompanyIdentityLookupRequest): NormalizableCompanyIdentityLookupRequest;
 /** True when the company has the minimum fields needed to render/persist a full
  * billing identity: legal name plus a complete registered address. Used to gate
  * whether a `partial` lookup is usable for its purpose. */

package/dist/company-identity/contracts.js

@@ -96,11 +96,9 @@ export const companyIdentitySourceSchema = z
     evidenceHash: z.string().trim().min(8).max(160).nullable(),
 })
     .strict();
-/** A lookup request. `country` is an open ISO-3166 alpha-2 code (not restricted
- * to any single country); `identifierKind`/`identifierValue` name and carry the
- * tax/registry id; `manualCompany` optionally seeds user-entered data an adapter
- * may reconcile against a registry. Parsing normalizes country to upper-case and
- * identifier kind to lower-case. */
+/** Lookup coordinates with optional manual identity for registry reconciliation.
+ * Country is an open ISO-3166 alpha-2 code. Parsing uppercases country and
+ * lowercases identifier kind; national tax-id rules belong to extensions. */
 /** @beta */
 export const companyIdentityLookupRequestSchema = z
     .object({
@@ -131,7 +129,8 @@ export const companyIdentityLookupResponseSchema = z
     warnings: z.array(z.string().trim().min(1).max(120)).default([]),
 })
     .strict();
-function normalizeCompanyIdentityLookupRequest(request) {
+/** @beta */
+export function normalizeCompanyIdentityLookupRequest(request) {
     const country = String(request.country).trim().toUpperCase();
     const identifierKind = String(request.identifierKind).trim().toLowerCase();
     const identifierValue = request.identifierValue.trim();

package/dist/company-identity/index.d.ts

@@ -1,5 +1,5 @@
 /** @beta */
-export { COMPANY_IDENTITY_CONTRACT_VERSION, companyIdentityAddressSchema, companyIdentityCompanySchema, companyIdentityIdentifierKindSchema, companyIdentityLookupRequestSchema, companyIdentityLookupResponseSchema, companyIdentityLookupStatusSchema, companyIdentityPurposeSchema, companyIdentitySourceSchema, companyIdentitySourceStatusSchema, companyIdentityVerificationLevelSchema, isCompleteCompanyIdentity, } from "./contracts.js";
+export { COMPANY_IDENTITY_CONTRACT_VERSION, companyIdentityAddressSchema, companyIdentityCompanySchema, companyIdentityIdentifierKindSchema, companyIdentityLookupRequestSchema, companyIdentityLookupResponseSchema, companyIdentityLookupStatusSchema, companyIdentityPurposeSchema, companyIdentitySourceSchema, companyIdentitySourceStatusSchema, companyIdentityVerificationLevelSchema, isCompleteCompanyIdentity, normalizeCompanyIdentityLookupRequest, } from "./contracts.js";
 /** @beta */
 export type { CompanyIdentityCompany, CompanyIdentityLookupRequest, CompanyIdentityLookupResponse, CompanyIdentityPurpose, CompanyIdentitySource, CompanyIdentitySourceStatus, CompanyIdentityVerificationLevel, } from "./contracts.js";
 /** @beta */

package/dist/company-identity/index.js

@@ -1,2 +1,2 @@
 /** @beta */
-export { COMPANY_IDENTITY_CONTRACT_VERSION, companyIdentityAddressSchema, companyIdentityCompanySchema, companyIdentityIdentifierKindSchema, companyIdentityLookupRequestSchema, companyIdentityLookupResponseSchema, companyIdentityLookupStatusSchema, companyIdentityPurposeSchema, companyIdentitySourceSchema, companyIdentitySourceStatusSchema, companyIdentityVerificationLevelSchema, isCompleteCompanyIdentity, } from "./contracts.js";
+export { COMPANY_IDENTITY_CONTRACT_VERSION, companyIdentityAddressSchema, companyIdentityCompanySchema, companyIdentityIdentifierKindSchema, companyIdentityLookupRequestSchema, companyIdentityLookupResponseSchema, companyIdentityLookupStatusSchema, companyIdentityPurposeSchema, companyIdentitySourceSchema, companyIdentitySourceStatusSchema, companyIdentityVerificationLevelSchema, isCompleteCompanyIdentity, normalizeCompanyIdentityLookupRequest, } from "./contracts.js";

package/dist/subscription/cycleHardening.d.ts

@@ -2,7 +2,7 @@
  * Subscription cycle hardening helpers — the canonical retry ladder a renewal
  * payment failure follows.
  *
- * This module is the SINGLE authority on the ladder. It answers three questions:
+ * This module is the SINGLE authority on the ladder. It answers four questions:
  *
  *   - `nextRetryAttemptAt(failedAt, attemptNumber, cadence?, failureClass?)` —
  *     when the next charge is due, or `null` when no next charge is due.
@@ -10,6 +10,8 @@
  *     — whether a failed payment may move into `retry_scheduled`.
  *   - `ladderTerminatedByClass(failureClass, cadence?)` — whether the REASON for
  *     the refusal, rather than the rung reached, ends the ladder.
+ *   - `isDunningLadderExhausted(cycle, cadence?)` — whether a refused cycle has
+ *     run past the last rung, the only non-payment reason to pause.
  *
  * TERMINATING, not capping. An attempt past the end of the ladder answers
  * `null`, which is the pause signal; it does not answer "the last slot again".
@@ -70,3 +72,24 @@ export declare function nextRetryAttemptAt(failedAtIso: string, attemptNumber: n
 export declare function shouldScheduleRetry(cycleStatus: CycleHandlerStatus, attemptNumber: number, cadence?: CycleRetryCadence, failureClass?: string | null): boolean;
 /** @beta */
 export declare function maxRetryAttempts(cadence?: CycleRetryCadence): number;
+/**
+ * Whether a refused cycle has EXHAUSTED the ladder: it failed, nothing is
+ * scheduled after it, and the attempt that failed sits past the last rung.
+ *
+ * This is the one condition under which the platform may pause a live
+ * subscription for non-payment. Both halves are required. An absent schedule on
+ * its own is not exhaustion: a class-terminated refusal on rung one also leaves
+ * nothing scheduled, and treating it as exhaustion would pause a subscription on
+ * the day of its first refusal. The rung is derived from the cadence, so pass
+ * the same cadence here and to `recordPaymentFailure`. The managed SQL dunning
+ * boundary spells the shipped ladder's rung as a fixed constant
+ * (`v_ladder_exhausted_from`, 4); a deployment that publishes a different
+ * ladder must move that constant with it.
+ *
+ * @beta
+ */
+export declare function isDunningLadderExhausted(cycle: {
+    readonly status: CycleHandlerStatus;
+    readonly retryAttempt: number;
+    readonly nextRetryAt: string | null;
+}, cadence?: CycleRetryCadence): boolean;

package/dist/subscription/cycleHardening.js

@@ -2,7 +2,7 @@
  * Subscription cycle hardening helpers — the canonical retry ladder a renewal
  * payment failure follows.
  *
- * This module is the SINGLE authority on the ladder. It answers three questions:
+ * This module is the SINGLE authority on the ladder. It answers four questions:
  *
  *   - `nextRetryAttemptAt(failedAt, attemptNumber, cadence?, failureClass?)` —
  *     when the next charge is due, or `null` when no next charge is due.
@@ -10,6 +10,8 @@
  *     — whether a failed payment may move into `retry_scheduled`.
  *   - `ladderTerminatedByClass(failureClass, cadence?)` — whether the REASON for
  *     the refusal, rather than the rung reached, ends the ladder.
+ *   - `isDunningLadderExhausted(cycle, cadence?)` — whether a refused cycle has
+ *     run past the last rung, the only non-payment reason to pause.
  *
  * TERMINATING, not capping. An attempt past the end of the ladder answers
  * `null`, which is the pause signal; it does not answer "the last slot again".
@@ -93,3 +95,24 @@ export function shouldScheduleRetry(cycleStatus, attemptNumber, cadence = DEFAUL
 export function maxRetryAttempts(cadence = DEFAULT_CYCLE_RETRY_CADENCE) {
     return cadence.backoffHours.length;
 }
+/**
+ * Whether a refused cycle has EXHAUSTED the ladder: it failed, nothing is
+ * scheduled after it, and the attempt that failed sits past the last rung.
+ *
+ * This is the one condition under which the platform may pause a live
+ * subscription for non-payment. Both halves are required. An absent schedule on
+ * its own is not exhaustion: a class-terminated refusal on rung one also leaves
+ * nothing scheduled, and treating it as exhaustion would pause a subscription on
+ * the day of its first refusal. The rung is derived from the cadence, so pass
+ * the same cadence here and to `recordPaymentFailure`. The managed SQL dunning
+ * boundary spells the shipped ladder's rung as a fixed constant
+ * (`v_ladder_exhausted_from`, 4); a deployment that publishes a different
+ * ladder must move that constant with it.
+ *
+ * @beta
+ */
+export function isDunningLadderExhausted(cycle, cadence = DEFAULT_CYCLE_RETRY_CADENCE) {
+    return (cycle.status === "payment_failed" &&
+        cycle.nextRetryAt === null &&
+        cycle.retryAttempt > maxRetryAttempts(cadence));
+}

package/dist/subscription/subscriptionEngineLifecycle.d.ts

@@ -1,5 +1,6 @@
-import type { SubscriptionLineSnapshot } from "./types.js";
-import type { EngineSubscription, SubscriptionEngineResult, SubscriptionMutationResult } from "./subscriptionEngineTypes.js";
+import type { SubscriptionLineSnapshot, SubscriptionStatus } from "./types.js";
+import { type CycleRetryCadence } from "./cycleHardening.js";
+import type { EngineCycle, EngineSubscription, SubscriptionEngineResult, SubscriptionMutationResult } from "./subscriptionEngineTypes.js";
 /** @beta */
 export declare function swapTemplateLine(input: {
     subscription: EngineSubscription;
@@ -50,3 +51,100 @@ export declare function completeSubscription(input: {
     subscription: EngineSubscription;
     now: string;
 }): SubscriptionEngineResult<SubscriptionMutationResult>;
+/**
+ * Win-back: the owner reactivates their own cancelled subscription.
+ *
+ * Mirrors the `cancelled -> active` edge of the managed SQL guard
+ * `public.subscription_guard_status_transition` and the customer `reactivate`
+ * action behind it. A reactivation charges again, so it needs a stored payment
+ * method, and it re-arms the next cycle {@link RESTART_LEAD_DAYS} out rather
+ * than leaving a stale instant that would make the renewal due immediately.
+ * The SQL action also clears the end instant and cancellation reason, requires
+ * the customer's confirmation of the charge timing, refuses while a cycle is
+ * locked and bumps the template version; those durable duties stay with the
+ * host.
+ *
+ * @beta
+ */
+export declare function reactivateSubscription(input: {
+    subscription: EngineSubscription;
+    now: string;
+    reason?: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult>;
+/**
+ * The sanctioned non-payment rule: a cycle that exhausted the retry ladder
+ * pauses an ACTIVE subscription.
+ *
+ * This is the only path in the engine that suspends a live subscription for a
+ * reason the owner did not choose, and it fires only when
+ * {@link isDunningLadderExhausted} holds for the refused cycle. A ladder cut
+ * short by a terminating refusal class, or a failure on any rung that still has
+ * a retry after it, is refused as `dunning_not_exhausted` and leaves the
+ * subscription untouched. A subscription that is not active (already paused,
+ * cancelled or completed) is returned unchanged with no event, which is what
+ * the managed SQL dunning boundary does and what makes a replay harmless.
+ *
+ * The schedule is not touched: pausing never moves `nextCycleAt`.
+ *
+ * @beta
+ */
+export declare function pauseSubscriptionForExpiredDunning(input: {
+    subscription: EngineSubscription;
+    cycle: EngineCycle;
+    now: string;
+    cadence?: CycleRetryCadence;
+}): SubscriptionEngineResult<SubscriptionMutationResult>;
+/**
+ * Customer-initiated recovery out of the non-payment pause.
+ *
+ * Mirrors the managed SQL `subscription_resume_after_expired_dunning`: the
+ * subscription must be paused and the cycle it passes must be the refused cycle
+ * that exhausted the ladder (the caller passes the LATEST such cycle, as the SQL
+ * boundary reads the latest dunning case). A new payment method, when given,
+ * replaces the stored one; without any method the resume is refused. Whether
+ * the method is chargeable unattended is the host's check, as it is in SQL.
+ * The given cycle becomes `skipped` rather than being charged late; the SQL
+ * boundary skips every uncollected cycle, so a host that holds more than one
+ * must skip the rest itself. The next cycle is re-armed
+ * {@link RESTART_LEAD_DAYS} out.
+ *
+ * @beta
+ */
+export declare function resumeSubscriptionFromExpiredDunning(input: {
+    subscription: EngineSubscription;
+    cycle: EngineCycle;
+    now: string;
+    paymentMethodRef?: string | null;
+    paymentMethodKind?: string | null;
+    cadence?: CycleRetryCadence;
+}): SubscriptionEngineResult<SubscriptionMutationResult & {
+    cycle: EngineCycle;
+}>;
+/**
+ * How far out a restarted subscription's next cycle is re-armed, in days. Both
+ * managed SQL restart paths (the customer `reactivate` action and
+ * `subscription_resume_after_expired_dunning`) spell it `interval '2 days'`.
+ *
+ * @beta
+ */
+export declare const RESTART_LEAD_DAYS = 2;
+/**
+ * The engine's subscription status matrix: every edge a status may take, and
+ * nothing else.
+ *
+ * It mirrors the managed SQL guard `public.subscription_guard_status_transition`
+ * over the four statuses the engine manages. The guard's remaining edges belong
+ * to the activation flow the engine never drives (`pending_activation` ->
+ * `active` / `activation_failed` / `cancelled`, and the audited expired-checkout
+ * reopen `cancelled` -> `pending_activation`). `completed` is terminal on both
+ * sides. `cancelled` -> `active` is the owner's win-back.
+ *
+ * Which OPERATION may take an edge is narrower than the matrix: `active` ->
+ * `paused` is the owner's pause or {@link pauseSubscriptionForExpiredDunning},
+ * and `cancelled` -> `active` is only {@link reactivateSubscription}.
+ *
+ * @beta
+ */
+export declare const SUBSCRIPTION_STATUS_TRANSITIONS: Readonly<Record<SubscriptionStatus, readonly SubscriptionStatus[]>>;
+/** @beta */
+export declare function canTransitionSubscriptionStatus(from: SubscriptionStatus, to: SubscriptionStatus): boolean;

package/dist/subscription/subscriptionEngineLifecycle.js

@@ -1,4 +1,5 @@
 import { isEditWindowOpen } from "./subscriptionEngineCore.js";
+import { DEFAULT_CYCLE_RETRY_CADENCE, isDunningLadderExhausted, } from "./cycleHardening.js";
 import { addCadenceDays, cloneTemplate, failure, makeEvent, parseIso, statusPatch, success, touchSubscription, validateTemplate, } from "./subscriptionEngineUtils.js";
 /** @beta */
 export function swapTemplateLine(input) {
@@ -127,7 +128,11 @@ export function pauseSubscription(input) {
 }
 /** @beta */
 export function resumeSubscription(input) {
-    return changeSubscriptionStatus(input.subscription, "active", input.now, "subscription.resumed", {});
+    // Resume leaves `paused` only. Leaving `cancelled` is a win-back and goes
+    // through reactivateSubscription, which re-arms the schedule. A subscription
+    // the exhausted ladder paused must resume through
+    // resumeSubscriptionFromExpiredDunning, which skips the uncollected cycle.
+    return changeSubscriptionStatus(input.subscription, "active", input.now, "subscription.resumed", {}, ["paused"]);
 }
 /** @beta */
 export function cancelSubscription(input) {
@@ -139,6 +144,171 @@ export function cancelSubscription(input) {
 export function completeSubscription(input) {
     return changeSubscriptionStatus(input.subscription, "completed", input.now, "subscription.completed", {});
 }
+/**
+ * Win-back: the owner reactivates their own cancelled subscription.
+ *
+ * Mirrors the `cancelled -> active` edge of the managed SQL guard
+ * `public.subscription_guard_status_transition` and the customer `reactivate`
+ * action behind it. A reactivation charges again, so it needs a stored payment
+ * method, and it re-arms the next cycle {@link RESTART_LEAD_DAYS} out rather
+ * than leaving a stale instant that would make the renewal due immediately.
+ * The SQL action also clears the end instant and cancellation reason, requires
+ * the customer's confirmation of the charge timing, refuses while a cycle is
+ * locked and bumps the template version; those durable duties stay with the
+ * host.
+ *
+ * @beta
+ */
+export function reactivateSubscription(input) {
+    const now = parseIso(input.now);
+    if (!now)
+        return failure("invalid_timestamp", "now must be a valid ISO timestamp");
+    if (input.subscription.status !== "cancelled") {
+        return failure("invalid_transition", `Cannot reactivate a subscription that is ${input.subscription.status}; only cancelled subscriptions can be won back`);
+    }
+    if (!input.subscription.paymentMethodRef) {
+        return failure("missing_payment_method", "reactivation requires a stored payment method");
+    }
+    const nextCycleAt = restartNextCycleAt(input.subscription, now);
+    if (!nextCycleAt)
+        return failure("invalid_timestamp", "restart exceeds the supported timestamp range");
+    return restart({
+        subscription: input.subscription,
+        now,
+        nextCycleAt,
+        idempotencyPrefix: `${input.subscription.id}:reactivated:${now.toISOString()}`,
+        payload: { reactivatedFrom: "cancelled", reason: input.reason ?? null },
+        leadingEvents: [],
+    });
+}
+/**
+ * The sanctioned non-payment rule: a cycle that exhausted the retry ladder
+ * pauses an ACTIVE subscription.
+ *
+ * This is the only path in the engine that suspends a live subscription for a
+ * reason the owner did not choose, and it fires only when
+ * {@link isDunningLadderExhausted} holds for the refused cycle. A ladder cut
+ * short by a terminating refusal class, or a failure on any rung that still has
+ * a retry after it, is refused as `dunning_not_exhausted` and leaves the
+ * subscription untouched. A subscription that is not active (already paused,
+ * cancelled or completed) is returned unchanged with no event, which is what
+ * the managed SQL dunning boundary does and what makes a replay harmless.
+ *
+ * The schedule is not touched: pausing never moves `nextCycleAt`.
+ *
+ * @beta
+ */
+export function pauseSubscriptionForExpiredDunning(input) {
+    const now = parseIso(input.now);
+    if (!now)
+        return failure("invalid_timestamp", "now must be a valid ISO timestamp");
+    const mismatch = cycleOwnershipError(input.subscription, input.cycle);
+    if (mismatch)
+        return mismatch;
+    if (!isDunningLadderExhausted(input.cycle, input.cadence ?? DEFAULT_CYCLE_RETRY_CADENCE)) {
+        return failure("dunning_not_exhausted", "only a cycle that exhausted the retry ladder may pause a subscription for non-payment");
+    }
+    if (input.subscription.status !== "active") {
+        return success({ subscription: touchSubscription(input.subscription, input.subscription.updatedAt, {}), events: [] });
+    }
+    const subscription = touchSubscription(input.subscription, now.toISOString(), statusPatch("paused"));
+    return success({
+        subscription,
+        events: [
+            makeEvent({
+                eventType: "subscription.paused",
+                subscription,
+                cycleNumber: input.cycle.cycleNumber,
+                idempotencyKey: `${input.cycle.engineIdempotencyKey}:subscription_paused`,
+                occurredAt: now.toISOString(),
+                payload: {
+                    reason: "payment_failed_expired",
+                    retryAttempt: input.cycle.retryAttempt,
+                    failureReason: input.cycle.failureReason,
+                },
+            }),
+        ],
+    });
+}
+/**
+ * Customer-initiated recovery out of the non-payment pause.
+ *
+ * Mirrors the managed SQL `subscription_resume_after_expired_dunning`: the
+ * subscription must be paused and the cycle it passes must be the refused cycle
+ * that exhausted the ladder (the caller passes the LATEST such cycle, as the SQL
+ * boundary reads the latest dunning case). A new payment method, when given,
+ * replaces the stored one; without any method the resume is refused. Whether
+ * the method is chargeable unattended is the host's check, as it is in SQL.
+ * The given cycle becomes `skipped` rather than being charged late; the SQL
+ * boundary skips every uncollected cycle, so a host that holds more than one
+ * must skip the rest itself. The next cycle is re-armed
+ * {@link RESTART_LEAD_DAYS} out.
+ *
+ * @beta
+ */
+export function resumeSubscriptionFromExpiredDunning(input) {
+    const now = parseIso(input.now);
+    if (!now)
+        return failure("invalid_timestamp", "now must be a valid ISO timestamp");
+    if (input.subscription.status !== "paused") {
+        return failure("invalid_transition", `Cannot resume a ${input.subscription.status} subscription from expired dunning; it must be paused`);
+    }
+    const mismatch = cycleOwnershipError(input.subscription, input.cycle);
+    if (mismatch)
+        return mismatch;
+    if (!isDunningLadderExhausted(input.cycle, input.cadence ?? DEFAULT_CYCLE_RETRY_CADENCE)) {
+        return failure("dunning_not_exhausted", "the cycle did not exhaust the retry ladder");
+    }
+    const replacementRef = input.paymentMethodRef?.trim() ? input.paymentMethodRef : null;
+    const method = replacementRef
+        ? {
+            paymentMethodRef: replacementRef,
+            paymentMethodKind: input.paymentMethodKind?.trim() || input.subscription.paymentMethodKind,
+        }
+        : {};
+    const withMethod = { ...input.subscription, ...method };
+    if (!withMethod.paymentMethodRef) {
+        return failure("missing_payment_method", "resuming requires a chargeable payment method");
+    }
+    const nextCycleAt = restartNextCycleAt(withMethod, now);
+    if (!nextCycleAt)
+        return failure("invalid_timestamp", "restart exceeds the supported timestamp range");
+    const cycle = { ...input.cycle, status: "skipped", nextRetryAt: null };
+    const restarted = restart({
+        subscription: withMethod,
+        now,
+        nextCycleAt,
+        idempotencyPrefix: `${input.cycle.engineIdempotencyKey}:resumed_after_expired_dunning`,
+        payload: {
+            resumedAfterExpiredDunning: true,
+            skippedCycleNumber: cycle.cycleNumber,
+        },
+        leadingEvents: [
+            makeEvent({
+                eventType: "subscription.cycle_skipped",
+                subscription: withMethod,
+                cycleNumber: cycle.cycleNumber,
+                idempotencyKey: `${input.cycle.engineIdempotencyKey}:cycle_skipped`,
+                occurredAt: now.toISOString(),
+                payload: {
+                    skippedScheduledAt: cycle.scheduledAt,
+                    reason: "subscription_resumed_after_expired_dunning",
+                },
+            }),
+        ],
+    });
+    if (restarted.ok === false)
+        return restarted;
+    return success({ ...restarted.value, cycle });
+}
+/**
+ * How far out a restarted subscription's next cycle is re-armed, in days. Both
+ * managed SQL restart paths (the customer `reactivate` action and
+ * `subscription_resume_after_expired_dunning`) spell it `interval '2 days'`.
+ *
+ * @beta
+ */
+export const RESTART_LEAD_DAYS = 2;
 function updateTemplate(input) {
     const now = parseIso(input.now);
     if (!now)
@@ -164,11 +334,12 @@ function updateTemplate(input) {
         ],
     });
 }
-function changeSubscriptionStatus(subscription, status, nowIso, eventType, payload) {
+function changeSubscriptionStatus(subscription, status, nowIso, eventType, payload, allowedFrom) {
     const now = parseIso(nowIso);
     if (!now)
         return failure("invalid_timestamp", "now must be a valid ISO timestamp");
-    if (!canTransitionSubscriptionStatus(subscription.status, status)) {
+    if ((allowedFrom !== undefined && !allowedFrom.includes(subscription.status)) ||
+        !canTransitionSubscriptionStatus(subscription.status, status)) {
         return failure("invalid_transition", `Cannot move subscription from ${subscription.status} to ${status}`);
     }
     const next = touchSubscription(subscription, now.toISOString(), statusPatch(status));
@@ -185,12 +356,78 @@ function changeSubscriptionStatus(subscription, status, nowIso, eventType, paylo
         ],
     });
 }
-function canTransitionSubscriptionStatus(from, to) {
-    const transitions = {
-        active: ["paused", "cancelled", "completed"],
-        paused: ["active", "cancelled"],
-        cancelled: [],
-        completed: [],
-    };
-    return transitions[from].includes(to);
+function restart(input) {
+    if (!canTransitionSubscriptionStatus(input.subscription.status, "active")) {
+        return failure("invalid_transition", `Cannot move subscription from ${input.subscription.status} to active`);
+    }
+    const occurredAt = input.now.toISOString();
+    const subscription = touchSubscription(input.subscription, occurredAt, {
+        ...statusPatch("active"),
+        nextCycleAt: input.nextCycleAt,
+    });
+    const events = [
+        ...input.leadingEvents,
+        makeEvent({
+            eventType: "subscription.resumed",
+            subscription,
+            idempotencyKey: `${input.idempotencyPrefix}:resumed`,
+            occurredAt,
+            payload: { ...input.payload, nextCycleAt: input.nextCycleAt },
+        }),
+    ];
+    if (input.nextCycleAt !== input.subscription.nextCycleAt) {
+        events.push(makeEvent({
+            eventType: "subscription.next_cycle_at_updated",
+            subscription,
+            idempotencyKey: `${input.idempotencyPrefix}:next_cycle_at_updated`,
+            occurredAt,
+            payload: { previousNextCycleAt: input.subscription.nextCycleAt, nextCycleAt: input.nextCycleAt },
+        }));
+    }
+    return success({ subscription, events });
+}
+// A restart re-arms the schedule RESTART_LEAD_DAYS out, but never earlier than
+// the instant already stored: the same monotonic clamp recordPaymentSuccess
+// applies, so a restart cannot pull a charge into a window already paid for.
+// The managed SQL restart paths assign `now + 2 days` without the clamp, so
+// the two differ exactly when the stored instant is later than that: a win-back
+// of a subscription paid through a later date, or a schedule skipped or slid
+// while the ladder was still running. There SQL charges earlier; this does not.
+function restartNextCycleAt(subscription, now) {
+    return new Date(Math.max(Date.parse(subscription.nextCycleAt) || 0, now.getTime() + RESTART_LEAD_DAYS * 24 * 60 * 60 * 1000)).toJSON();
+}
+function cycleOwnershipError(subscription, cycle) {
+    if (cycle.subscriptionId === subscription.id)
+        return null;
+    return failure("invalid_transition", "the cycle belongs to a different subscription");
+}
+/**
+ * The engine's subscription status matrix: every edge a status may take, and
+ * nothing else.
+ *
+ * It mirrors the managed SQL guard `public.subscription_guard_status_transition`
+ * over the four statuses the engine manages. The guard's remaining edges belong
+ * to the activation flow the engine never drives (`pending_activation` ->
+ * `active` / `activation_failed` / `cancelled`, and the audited expired-checkout
+ * reopen `cancelled` -> `pending_activation`). `completed` is terminal on both
+ * sides. `cancelled` -> `active` is the owner's win-back.
+ *
+ * Which OPERATION may take an edge is narrower than the matrix: `active` ->
+ * `paused` is the owner's pause or {@link pauseSubscriptionForExpiredDunning},
+ * and `cancelled` -> `active` is only {@link reactivateSubscription}.
+ *
+ * @beta
+ */
+export const SUBSCRIPTION_STATUS_TRANSITIONS = Object.freeze({
+    active: Object.freeze(["paused", "cancelled", "completed"]),
+    paused: Object.freeze(["active", "cancelled"]),
+    cancelled: Object.freeze(["active"]),
+    completed: Object.freeze([]),
+});
+/** @beta */
+export function canTransitionSubscriptionStatus(from, to) {
+    // Own keys only: a status read from storage is an untyped string, and
+    // "constructor" or "__proto__" must answer false rather than throw.
+    return Object.prototype.hasOwnProperty.call(SUBSCRIPTION_STATUS_TRANSITIONS, from) &&
+        SUBSCRIPTION_STATUS_TRANSITIONS[from].includes(to);
 }

package/dist/subscription/subscriptionEnginePayment.d.ts

@@ -1,3 +1,4 @@
+import { type CycleRetryCadence } from "./cycleHardening.js";
 import type { CycleMutationResult, EngineCycle, EngineEvent, EngineSubscription, SubscriptionEngineResult } from "./subscriptionEngineTypes.js";
 /** @beta */
 export declare function recordPaymentSuccess(input: {
@@ -16,4 +17,9 @@ export declare function recordPaymentFailure(input: {
     failedAt: string;
     reason: string;
     failureClass?: string | null;
+    /**
+     * The deployment's ladder. Pass the same cadence to
+     * `pauseSubscriptionForExpiredDunning` so both agree on exhaustion.
+     */
+    cadence?: CycleRetryCadence;
 }): SubscriptionEngineResult<CycleMutationResult>;

package/dist/subscription/subscriptionEnginePayment.js

@@ -94,7 +94,7 @@ export function recordPaymentFailure(input) {
     }
     const retryAttempt = input.cycle.retryAttempt + 1;
     // The ladder owns its terminal decision.
-    const nextRetryAt = nextRetryAttemptAt(failedAt.toISOString(), retryAttempt, undefined, input.failureClass);
+    const nextRetryAt = nextRetryAttemptAt(failedAt.toISOString(), retryAttempt, input.cadence, input.failureClass);
     const status = nextRetryAt ? "retry_scheduled" : "payment_failed";
     const cycle = {
         ...input.cycle,

package/dist/subscription/subscriptionEngineTypes.d.ts

@@ -4,7 +4,7 @@ export declare const DEFAULT_EDIT_WINDOW_HOURS = 72;
 /** @beta */
 export declare const DEFAULT_TIMEZONE = "UTC";
 /** @beta */
-export type SubscriptionEngineErrorCode = "invalid_timestamp" | "invalid_template" | "inactive_subscription" | "edit_window_closed" | "line_not_found" | "duplicate_line" | "invalid_slide_target" | "invalid_transition" | "terminal_cycle";
+export type SubscriptionEngineErrorCode = "invalid_timestamp" | "invalid_template" | "inactive_subscription" | "edit_window_closed" | "line_not_found" | "duplicate_line" | "invalid_slide_target" | "invalid_transition" | "terminal_cycle" | "missing_payment_method" | "dunning_not_exhausted";
 /** @beta */
 export type SubscriptionEngineResult<T> = {
     ok: true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlup/core",
-  "version": "0.6.0",
+  "version": "0.9.0",
   "description": "Neutral D2C subscription and bundle commerce kernels; a development preview with no stable API.",
   "license": "Apache-2.0",
   "repository": {

package/release-gates.json

@@ -209,9 +209,9 @@
     }
   },
   "pack": {
-    "$raiseReason": "2026-09-11, owner-approved: checkout refusal recovery adds two neutral contract and policy modules with their normal source, JavaScript and declaration outputs. The reviewed artifact measured 122504 packed bytes, 533693 unpacked bytes and 192 files before this note. Packed allowance increases by 2048 bytes and unpacked by 6144 bytes; maxFiles stays 192. Exports, dependencies, runtime behavior and all other release gates remain unchanged by this exception.",
-    "maxPackedBytes": 122880,
-    "maxUnpackedBytes": 534528,
+    "$raiseReason": "2026-09-27, owner-approved: the subscription status matrix, the win-back and the exhausted-ladder pause and resume add four functions, one predicate and two constants with their JSDoc, including the host duties the managed SQL restarts keep, JavaScript and declaration outputs, plus their changelog entry. Measured, not estimated: clean origin/main packs 122809 packed bytes, 534452 unpacked bytes and 192 files; this change packs about 130.3 thousand packed and 569.7 thousand unpacked bytes (rounded, because this note's own text moves the last digits) and 192 files. Packed allowance increases by 8192 bytes and unpacked by 38912 bytes; maxFiles stays 192. The package export map, dependencies and all other release gates are unchanged; the ./subscription entry gains named exports. The previous raise, 2026-09-11 and owner-approved, moved packed by 2048 and unpacked by 6144 bytes for checkout refusal recovery.",
+    "maxPackedBytes": 131072,
+    "maxUnpackedBytes": 573440,
     "maxFiles": 192,
     "requiredFiles": [
       "CHANGELOG.md",

package/src/company-identity/contracts.ts

@@ -106,11 +106,9 @@ export const companyIdentitySourceSchema = z
   })
   .strict();
 
-/** A lookup request. `country` is an open ISO-3166 alpha-2 code (not restricted
- * to any single country); `identifierKind`/`identifierValue` name and carry the
- * tax/registry id; `manualCompany` optionally seeds user-entered data an adapter
- * may reconcile against a registry. Parsing normalizes country to upper-case and
- * identifier kind to lower-case. */
+/** Lookup coordinates with optional manual identity for registry reconciliation.
+ * Country is an open ISO-3166 alpha-2 code. Parsing uppercases country and
+ * lowercases identifier kind; national tax-id rules belong to extensions. */
 /** @beta */
 export const companyIdentityLookupRequestSchema = z
   .object({
@@ -166,7 +164,8 @@ interface NormalizableCompanyIdentityLookupRequest {
   manualCompany?: Partial<CompanyIdentityCompany>;
 }
 
-function normalizeCompanyIdentityLookupRequest(
+/** @beta */
+export function normalizeCompanyIdentityLookupRequest(
   request: NormalizableCompanyIdentityLookupRequest,
 ): NormalizableCompanyIdentityLookupRequest {
   const country = String(request.country).trim().toUpperCase();

package/src/company-identity/index.ts

@@ -12,6 +12,7 @@ export {
   companyIdentitySourceStatusSchema,
   companyIdentityVerificationLevelSchema,
   isCompleteCompanyIdentity,
+  normalizeCompanyIdentityLookupRequest,
 } from "./contracts.js";
 /** @beta */
 export type {

package/src/subscription/cycleHardening.ts

@@ -2,7 +2,7 @@
  * Subscription cycle hardening helpers — the canonical retry ladder a renewal
  * payment failure follows.
  *
- * This module is the SINGLE authority on the ladder. It answers three questions:
+ * This module is the SINGLE authority on the ladder. It answers four questions:
  *
  *   - `nextRetryAttemptAt(failedAt, attemptNumber, cadence?, failureClass?)` —
  *     when the next charge is due, or `null` when no next charge is due.
@@ -10,6 +10,8 @@
  *     — whether a failed payment may move into `retry_scheduled`.
  *   - `ladderTerminatedByClass(failureClass, cadence?)` — whether the REASON for
  *     the refusal, rather than the rung reached, ends the ladder.
+ *   - `isDunningLadderExhausted(cycle, cadence?)` — whether a refused cycle has
+ *     run past the last rung, the only non-payment reason to pause.
  *
  * TERMINATING, not capping. An attempt past the end of the ladder answers
  * `null`, which is the pause signal; it does not answer "the last slot again".
@@ -139,3 +141,34 @@ export function maxRetryAttempts(
 ): number {
   return cadence.backoffHours.length;
 }
+
+/**
+ * Whether a refused cycle has EXHAUSTED the ladder: it failed, nothing is
+ * scheduled after it, and the attempt that failed sits past the last rung.
+ *
+ * This is the one condition under which the platform may pause a live
+ * subscription for non-payment. Both halves are required. An absent schedule on
+ * its own is not exhaustion: a class-terminated refusal on rung one also leaves
+ * nothing scheduled, and treating it as exhaustion would pause a subscription on
+ * the day of its first refusal. The rung is derived from the cadence, so pass
+ * the same cadence here and to `recordPaymentFailure`. The managed SQL dunning
+ * boundary spells the shipped ladder's rung as a fixed constant
+ * (`v_ladder_exhausted_from`, 4); a deployment that publishes a different
+ * ladder must move that constant with it.
+ *
+ * @beta
+ */
+export function isDunningLadderExhausted(
+  cycle: {
+    readonly status: CycleHandlerStatus;
+    readonly retryAttempt: number;
+    readonly nextRetryAt: string | null;
+  },
+  cadence: CycleRetryCadence = DEFAULT_CYCLE_RETRY_CADENCE,
+): boolean {
+  return (
+    cycle.status === "payment_failed" &&
+    cycle.nextRetryAt === null &&
+    cycle.retryAttempt > maxRetryAttempts(cadence)
+  );
+}

package/src/subscription/subscriptionEngineLifecycle.ts

@@ -1,6 +1,13 @@
 import type { SubscriptionEngineEventType, SubscriptionLineSnapshot, SubscriptionStatus } from "./types.js";
 import { isEditWindowOpen } from "./subscriptionEngineCore.js";
+import {
+  DEFAULT_CYCLE_RETRY_CADENCE,
+  isDunningLadderExhausted,
+  type CycleRetryCadence,
+} from "./cycleHardening.js";
 import type {
+  EngineCycle,
+  EngineEvent,
   EngineSubscription,
   SubscriptionEngineResult,
   SubscriptionMutationResult,
@@ -184,7 +191,11 @@ export function resumeSubscription(input: {
   subscription: EngineSubscription;
   now: string;
 }): SubscriptionEngineResult<SubscriptionMutationResult> {
-  return changeSubscriptionStatus(input.subscription, "active", input.now, "subscription.resumed", {});
+  // Resume leaves `paused` only. Leaving `cancelled` is a win-back and goes
+  // through reactivateSubscription, which re-arms the schedule. A subscription
+  // the exhausted ladder paused must resume through
+  // resumeSubscriptionFromExpiredDunning, which skips the uncollected cycle.
+  return changeSubscriptionStatus(input.subscription, "active", input.now, "subscription.resumed", {}, ["paused"]);
 }
 
 /** @beta */
@@ -206,6 +217,198 @@ export function completeSubscription(input: {
   return changeSubscriptionStatus(input.subscription, "completed", input.now, "subscription.completed", {});
 }
 
+/**
+ * Win-back: the owner reactivates their own cancelled subscription.
+ *
+ * Mirrors the `cancelled -> active` edge of the managed SQL guard
+ * `public.subscription_guard_status_transition` and the customer `reactivate`
+ * action behind it. A reactivation charges again, so it needs a stored payment
+ * method, and it re-arms the next cycle {@link RESTART_LEAD_DAYS} out rather
+ * than leaving a stale instant that would make the renewal due immediately.
+ * The SQL action also clears the end instant and cancellation reason, requires
+ * the customer's confirmation of the charge timing, refuses while a cycle is
+ * locked and bumps the template version; those durable duties stay with the
+ * host.
+ *
+ * @beta
+ */
+export function reactivateSubscription(input: {
+  subscription: EngineSubscription;
+  now: string;
+  reason?: string;
+}): SubscriptionEngineResult<SubscriptionMutationResult> {
+  const now = parseIso(input.now);
+  if (!now) return failure("invalid_timestamp", "now must be a valid ISO timestamp");
+  if (input.subscription.status !== "cancelled") {
+    return failure(
+      "invalid_transition",
+      `Cannot reactivate a subscription that is ${input.subscription.status}; only cancelled subscriptions can be won back`,
+    );
+  }
+  if (!input.subscription.paymentMethodRef) {
+    return failure("missing_payment_method", "reactivation requires a stored payment method");
+  }
+
+  const nextCycleAt = restartNextCycleAt(input.subscription, now);
+  if (!nextCycleAt) return failure("invalid_timestamp", "restart exceeds the supported timestamp range");
+
+  return restart({
+    subscription: input.subscription,
+    now,
+    nextCycleAt,
+    idempotencyPrefix: `${input.subscription.id}:reactivated:${now.toISOString()}`,
+    payload: { reactivatedFrom: "cancelled", reason: input.reason ?? null },
+    leadingEvents: [],
+  });
+}
+
+/**
+ * The sanctioned non-payment rule: a cycle that exhausted the retry ladder
+ * pauses an ACTIVE subscription.
+ *
+ * This is the only path in the engine that suspends a live subscription for a
+ * reason the owner did not choose, and it fires only when
+ * {@link isDunningLadderExhausted} holds for the refused cycle. A ladder cut
+ * short by a terminating refusal class, or a failure on any rung that still has
+ * a retry after it, is refused as `dunning_not_exhausted` and leaves the
+ * subscription untouched. A subscription that is not active (already paused,
+ * cancelled or completed) is returned unchanged with no event, which is what
+ * the managed SQL dunning boundary does and what makes a replay harmless.
+ *
+ * The schedule is not touched: pausing never moves `nextCycleAt`.
+ *
+ * @beta
+ */
+export function pauseSubscriptionForExpiredDunning(input: {
+  subscription: EngineSubscription;
+  cycle: EngineCycle;
+  now: string;
+  cadence?: CycleRetryCadence;
+}): SubscriptionEngineResult<SubscriptionMutationResult> {
+  const now = parseIso(input.now);
+  if (!now) return failure("invalid_timestamp", "now must be a valid ISO timestamp");
+  const mismatch = cycleOwnershipError(input.subscription, input.cycle);
+  if (mismatch) return mismatch;
+  if (!isDunningLadderExhausted(input.cycle, input.cadence ?? DEFAULT_CYCLE_RETRY_CADENCE)) {
+    return failure(
+      "dunning_not_exhausted",
+      "only a cycle that exhausted the retry ladder may pause a subscription for non-payment",
+    );
+  }
+  if (input.subscription.status !== "active") {
+    return success({ subscription: touchSubscription(input.subscription, input.subscription.updatedAt, {}), events: [] });
+  }
+
+  const subscription = touchSubscription(input.subscription, now.toISOString(), statusPatch("paused"));
+  return success({
+    subscription,
+    events: [
+      makeEvent({
+        eventType: "subscription.paused",
+        subscription,
+        cycleNumber: input.cycle.cycleNumber,
+        idempotencyKey: `${input.cycle.engineIdempotencyKey}:subscription_paused`,
+        occurredAt: now.toISOString(),
+        payload: {
+          reason: "payment_failed_expired",
+          retryAttempt: input.cycle.retryAttempt,
+          failureReason: input.cycle.failureReason,
+        },
+      }),
+    ],
+  });
+}
+
+/**
+ * Customer-initiated recovery out of the non-payment pause.
+ *
+ * Mirrors the managed SQL `subscription_resume_after_expired_dunning`: the
+ * subscription must be paused and the cycle it passes must be the refused cycle
+ * that exhausted the ladder (the caller passes the LATEST such cycle, as the SQL
+ * boundary reads the latest dunning case). A new payment method, when given,
+ * replaces the stored one; without any method the resume is refused. Whether
+ * the method is chargeable unattended is the host's check, as it is in SQL.
+ * The given cycle becomes `skipped` rather than being charged late; the SQL
+ * boundary skips every uncollected cycle, so a host that holds more than one
+ * must skip the rest itself. The next cycle is re-armed
+ * {@link RESTART_LEAD_DAYS} out.
+ *
+ * @beta
+ */
+export function resumeSubscriptionFromExpiredDunning(input: {
+  subscription: EngineSubscription;
+  cycle: EngineCycle;
+  now: string;
+  paymentMethodRef?: string | null;
+  paymentMethodKind?: string | null;
+  cadence?: CycleRetryCadence;
+}): SubscriptionEngineResult<SubscriptionMutationResult & { cycle: EngineCycle }> {
+  const now = parseIso(input.now);
+  if (!now) return failure("invalid_timestamp", "now must be a valid ISO timestamp");
+  if (input.subscription.status !== "paused") {
+    return failure(
+      "invalid_transition",
+      `Cannot resume a ${input.subscription.status} subscription from expired dunning; it must be paused`,
+    );
+  }
+  const mismatch = cycleOwnershipError(input.subscription, input.cycle);
+  if (mismatch) return mismatch;
+  if (!isDunningLadderExhausted(input.cycle, input.cadence ?? DEFAULT_CYCLE_RETRY_CADENCE)) {
+    return failure("dunning_not_exhausted", "the cycle did not exhaust the retry ladder");
+  }
+
+  const replacementRef = input.paymentMethodRef?.trim() ? input.paymentMethodRef : null;
+  const method: Partial<EngineSubscription> = replacementRef
+    ? {
+        paymentMethodRef: replacementRef,
+        paymentMethodKind: input.paymentMethodKind?.trim() || input.subscription.paymentMethodKind,
+      }
+    : {};
+  const withMethod = { ...input.subscription, ...method };
+  if (!withMethod.paymentMethodRef) {
+    return failure("missing_payment_method", "resuming requires a chargeable payment method");
+  }
+
+  const nextCycleAt = restartNextCycleAt(withMethod, now);
+  if (!nextCycleAt) return failure("invalid_timestamp", "restart exceeds the supported timestamp range");
+
+  const cycle: EngineCycle = { ...input.cycle, status: "skipped", nextRetryAt: null };
+  const restarted = restart({
+    subscription: withMethod,
+    now,
+    nextCycleAt,
+    idempotencyPrefix: `${input.cycle.engineIdempotencyKey}:resumed_after_expired_dunning`,
+    payload: {
+      resumedAfterExpiredDunning: true,
+      skippedCycleNumber: cycle.cycleNumber,
+    },
+    leadingEvents: [
+      makeEvent({
+        eventType: "subscription.cycle_skipped",
+        subscription: withMethod,
+        cycleNumber: cycle.cycleNumber,
+        idempotencyKey: `${input.cycle.engineIdempotencyKey}:cycle_skipped`,
+        occurredAt: now.toISOString(),
+        payload: {
+          skippedScheduledAt: cycle.scheduledAt,
+          reason: "subscription_resumed_after_expired_dunning",
+        },
+      }),
+    ],
+  });
+  if (restarted.ok === false) return restarted;
+  return success({ ...restarted.value, cycle });
+}
+
+/**
+ * How far out a restarted subscription's next cycle is re-armed, in days. Both
+ * managed SQL restart paths (the customer `reactivate` action and
+ * `subscription_resume_after_expired_dunning`) spell it `interval '2 days'`.
+ *
+ * @beta
+ */
+export const RESTART_LEAD_DAYS = 2;
+
 function updateTemplate(input: {
   subscription: EngineSubscription;
   template: EngineSubscription["template"];
@@ -245,10 +448,14 @@ function changeSubscriptionStatus(
   nowIso: string,
   eventType: SubscriptionEngineEventType,
   payload: Record<string, unknown>,
+  allowedFrom?: readonly SubscriptionStatus[],
 ): SubscriptionEngineResult<SubscriptionMutationResult> {
   const now = parseIso(nowIso);
   if (!now) return failure("invalid_timestamp", "now must be a valid ISO timestamp");
-  if (!canTransitionSubscriptionStatus(subscription.status, status)) {
+  if (
+    (allowedFrom !== undefined && !allowedFrom.includes(subscription.status)) ||
+    !canTransitionSubscriptionStatus(subscription.status, status)
+  ) {
     return failure(
       "invalid_transition",
       `Cannot move subscription from ${subscription.status} to ${status}`,
@@ -270,13 +477,98 @@ function changeSubscriptionStatus(
   });
 }
 
-function canTransitionSubscriptionStatus(from: SubscriptionStatus, to: SubscriptionStatus): boolean {
-  const transitions: Record<SubscriptionStatus, readonly SubscriptionStatus[]> = {
-    active: ["paused", "cancelled", "completed"],
-    paused: ["active", "cancelled"],
-    cancelled: [],
-    completed: [],
-  };
+function restart(input: {
+  subscription: EngineSubscription;
+  now: Date;
+  nextCycleAt: string;
+  idempotencyPrefix: string;
+  payload: Record<string, unknown>;
+  leadingEvents: EngineEvent[];
+}): SubscriptionEngineResult<SubscriptionMutationResult> {
+  if (!canTransitionSubscriptionStatus(input.subscription.status, "active")) {
+    return failure("invalid_transition", `Cannot move subscription from ${input.subscription.status} to active`);
+  }
+  const occurredAt = input.now.toISOString();
+  const subscription = touchSubscription(input.subscription, occurredAt, {
+    ...statusPatch("active"),
+    nextCycleAt: input.nextCycleAt,
+  });
+  const events = [
+    ...input.leadingEvents,
+    makeEvent({
+      eventType: "subscription.resumed",
+      subscription,
+      idempotencyKey: `${input.idempotencyPrefix}:resumed`,
+      occurredAt,
+      payload: { ...input.payload, nextCycleAt: input.nextCycleAt },
+    }),
+  ];
+  if (input.nextCycleAt !== input.subscription.nextCycleAt) {
+    events.push(
+      makeEvent({
+        eventType: "subscription.next_cycle_at_updated",
+        subscription,
+        idempotencyKey: `${input.idempotencyPrefix}:next_cycle_at_updated`,
+        occurredAt,
+        payload: { previousNextCycleAt: input.subscription.nextCycleAt, nextCycleAt: input.nextCycleAt },
+      }),
+    );
+  }
+  return success({ subscription, events });
+}
+
+// A restart re-arms the schedule RESTART_LEAD_DAYS out, but never earlier than
+// the instant already stored: the same monotonic clamp recordPaymentSuccess
+// applies, so a restart cannot pull a charge into a window already paid for.
+// The managed SQL restart paths assign `now + 2 days` without the clamp, so
+// the two differ exactly when the stored instant is later than that: a win-back
+// of a subscription paid through a later date, or a schedule skipped or slid
+// while the ladder was still running. There SQL charges earlier; this does not.
+function restartNextCycleAt(subscription: EngineSubscription, now: Date): string | null {
+  return new Date(Math.max(
+    Date.parse(subscription.nextCycleAt) || 0,
+    now.getTime() + RESTART_LEAD_DAYS * 24 * 60 * 60 * 1000,
+  )).toJSON();
+}
 
-  return transitions[from].includes(to);
+function cycleOwnershipError(
+  subscription: EngineSubscription,
+  cycle: EngineCycle,
+): SubscriptionEngineResult<never> | null {
+  if (cycle.subscriptionId === subscription.id) return null;
+  return failure("invalid_transition", "the cycle belongs to a different subscription");
+}
+
+/**
+ * The engine's subscription status matrix: every edge a status may take, and
+ * nothing else.
+ *
+ * It mirrors the managed SQL guard `public.subscription_guard_status_transition`
+ * over the four statuses the engine manages. The guard's remaining edges belong
+ * to the activation flow the engine never drives (`pending_activation` ->
+ * `active` / `activation_failed` / `cancelled`, and the audited expired-checkout
+ * reopen `cancelled` -> `pending_activation`). `completed` is terminal on both
+ * sides. `cancelled` -> `active` is the owner's win-back.
+ *
+ * Which OPERATION may take an edge is narrower than the matrix: `active` ->
+ * `paused` is the owner's pause or {@link pauseSubscriptionForExpiredDunning},
+ * and `cancelled` -> `active` is only {@link reactivateSubscription}.
+ *
+ * @beta
+ */
+export const SUBSCRIPTION_STATUS_TRANSITIONS: Readonly<
+  Record<SubscriptionStatus, readonly SubscriptionStatus[]>
+> = Object.freeze({
+  active: Object.freeze(["paused", "cancelled", "completed"] as const),
+  paused: Object.freeze(["active", "cancelled"] as const),
+  cancelled: Object.freeze(["active"] as const),
+  completed: Object.freeze([] as const),
+});
+
+/** @beta */
+export function canTransitionSubscriptionStatus(from: SubscriptionStatus, to: SubscriptionStatus): boolean {
+  // Own keys only: a status read from storage is an untyped string, and
+  // "constructor" or "__proto__" must answer false rather than throw.
+  return Object.prototype.hasOwnProperty.call(SUBSCRIPTION_STATUS_TRANSITIONS, from) &&
+    SUBSCRIPTION_STATUS_TRANSITIONS[from].includes(to);
 }

package/src/subscription/subscriptionEnginePayment.ts

@@ -1,4 +1,4 @@
-import { nextRetryAttemptAt } from "./cycleHardening.js";
+import { nextRetryAttemptAt, type CycleRetryCadence } from "./cycleHardening.js";
 import type { SubscriptionCycleStatus } from "./types.js";
 import type {
   CycleMutationResult,
@@ -124,6 +124,11 @@ export function recordPaymentFailure(input: {
   failedAt: string;
   reason: string;
   failureClass?: string | null;
+  /**
+   * The deployment's ladder. Pass the same cadence to
+   * `pauseSubscriptionForExpiredDunning` so both agree on exhaustion.
+   */
+  cadence?: CycleRetryCadence;
 }): SubscriptionEngineResult<CycleMutationResult> {
   const failedAt = parseIso(input.failedAt);
   if (!failedAt) return failure("invalid_timestamp", "failedAt must be a valid ISO timestamp");
@@ -136,7 +141,7 @@ export function recordPaymentFailure(input: {
   const nextRetryAt = nextRetryAttemptAt(
     failedAt.toISOString(),
     retryAttempt,
-    undefined,
+    input.cadence,
     input.failureClass,
   );
   const status: SubscriptionCycleStatus = nextRetryAt ? "retry_scheduled" : "payment_failed";

package/src/subscription/subscriptionEngineTypes.ts

@@ -20,7 +20,9 @@ export type SubscriptionEngineErrorCode =
   | "duplicate_line"
   | "invalid_slide_target"
   | "invalid_transition"
-  | "terminal_cycle";
+  | "terminal_cycle"
+  | "missing_payment_method"
+  | "dunning_not_exhausted";
 
 /** @beta */
 export type SubscriptionEngineResult<T> =