@openlup/core 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -10,6 +10,20 @@ in the source repository.
 
 ## [Unreleased]
 
+## [0.26.0]
+
+- Publishable on the npm `latest` dist-tag as `0.26.0`, from tag
+  `openlup-core-v0.26.0`.
+
+## [0.25.0]
+
+- Publishable on the npm `latest` dist-tag as `0.25.0`, from tag
+  `openlup-core-v0.25.0`.
+
+- Keep active subscriptions unchanged when the retry ladder is exhausted; the compatibility function emits no pause event and retains historical paused-row recovery.
+
+Migration notes: Exhaustion no longer changes an active subscription to paused. Existing paused records are not rewritten; explicit customer lifecycle commands and historical recovery remain separate.
+
 ## [0.24.0]
 
 - Publishable on the npm `latest` dist-tag as `0.24.0`, from tag
@@ -26,33 +40,3 @@ Migration: upgrade the complete set together for exact internal peers; core intr
 ### Known limitations
 
 The fulfillment status map retains localized adopter labels; hosts still need injected labels or internationalization keys.
-
-## [0.23.0]
-
-- Publishable on the npm `latest` dist-tag as `0.23.0`, from tag
-  `openlup-core-v0.23.0`.
-
-- Republish unchanged APIs, runtime behavior and shipped SQL from `0.22.0` as part of the complete `0.23.0` package set.
-
-Migration: upgrade the complete set together for exact internal peers; core introduces no API or schema migration.
-
-### Known limitations
-
-The fulfillment status map retains localized adopter labels; hosts still need injected labels or internationalization keys.
-
-## [0.22.0]
-
-- Publishable on the npm `latest` dist-tag as `0.22.0`, from tag
-  `openlup-core-v0.22.0`.
-
-- Add pure fulfillment status, tracking-progress, current-parcel and canonical
-  fact-parser helpers to the existing `./fulfillment` subpath. Generic fact types
-  retain their names; narrowed fact aliases use the `Canonical` prefix. New
-  fulfillment re-exports carry the same `@beta` annotation as existing facts.
-
-Migration: existing platform fulfillment imports remain compatible re-exports;
-no application import or schema migration is required.
-
-### Known limitations
-
-- `FULFILLMENT_STATUS_MAP` carries localized adopter labels. Replace them with host-injected labels or internationalization keys before any stable-framework claim.

package/README.md

@@ -8,11 +8,12 @@ application" section, which `docs:check` requires, tells an application's agent
 not to edit or patch the installed package and to upgrade every `@openlup/*`
 package together.
 
-The prepared `0.24.0` set carries the Zod validation floor below; remaining APIs,
-runtime behavior and shipped SQL are unchanged from `0.23.0`.
-Upgrade all packages together and read [the migration and label limitation](CHANGELOG.md#0240).
-The size baseline is the published `0.23.0` artifact; older releases remain in
-the source-only `CHANGELOG-HISTORY.md`. Preparation establishes no npm publication.
+The prepared `0.26.0` set republishes this kernel with the platform's managed
+dunning attempt-replay changes. Upgrade all packages together and read
+[the migration notes](CHANGELOG.md#0260), including the platform's required
+nullable failure-attempt field. The size baseline is the published `0.25.0`
+artifact; older releases remain in the source-only `CHANGELOG-HISTORY.md`.
+Preparation establishes no npm publication.
 
 The prepared set requires Zod `^4.6.6` for GHSA-mrhx-c7xc-m3w5.
 Oversized constrained collections fail before per-element errors accumulate;

package/dist/subscription/cycleHardening.d.ts

@@ -11,10 +11,11 @@
  *   - `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.
+ *     run past the last rung; exhaustion leaves the subscription active.
  *
  * 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".
+ * `null`, which ends automatic retries without pausing the subscription; it never
+ * answers "the last slot again".
  * Callers therefore never need a `attempt <= maxRetryAttempts()` guard of their
  * own — asking for the next slot IS the decision, and a second copy of the
  * budget check is exactly how two rails drift apart.
@@ -76,15 +77,11 @@ 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.
+ * Exhaustion stops automatic retries; it never pauses the subscription.
+ * An absent schedule alone is not exhaustion: a terminating refusal class can
+ * leave no retry on the first rung. Pass the same cadence here and to
+ * `recordPaymentFailure`. Legacy expired-dunning recovery also uses this
+ * predicate to distinguish an exhausted cycle from an early refusal.
  *
  * @beta
  */

package/dist/subscription/cycleHardening.js

@@ -11,10 +11,11 @@
  *   - `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.
+ *     run past the last rung; exhaustion leaves the subscription active.
  *
  * 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".
+ * `null`, which ends automatic retries without pausing the subscription; it never
+ * answers "the last slot again".
  * Callers therefore never need a `attempt <= maxRetryAttempts()` guard of their
  * own — asking for the next slot IS the decision, and a second copy of the
  * budget check is exactly how two rails drift apart.
@@ -99,15 +100,11 @@ export function maxRetryAttempts(cadence = DEFAULT_CYCLE_RETRY_CADENCE) {
  * 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.
+ * Exhaustion stops automatic retries; it never pauses the subscription.
+ * An absent schedule alone is not exhaustion: a terminating refusal class can
+ * leave no retry on the first rung. Pass the same cadence here and to
+ * `recordPaymentFailure`. Legacy expired-dunning recovery also uses this
+ * predicate to distinguish an exhausted cycle from an early refusal.
  *
  * @beta
  */

package/dist/subscription/subscriptionEngineLifecycle.d.ts

@@ -72,19 +72,11 @@ export declare function reactivateSubscription(input: {
     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`.
+ * Compatibility entry point for an exhausted retry ladder. Exhaustion leaves
+ * the subscription unchanged and emits no pause event. The unpaid cycle stays
+ * available for authorized recovery; it never starts a new cycle implicitly.
+ * Below exhaustion the call still refuses as `dunning_not_exhausted`.
+ * Explicit owner pauses and legacy expired-dunning recovery remain separate.
  *
  * @beta
  */
@@ -95,7 +87,7 @@ export declare function pauseSubscriptionForExpiredDunning(input: {
     cadence?: CycleRetryCadence;
 }): SubscriptionEngineResult<SubscriptionMutationResult>;
 /**
- * Customer-initiated recovery out of the non-payment pause.
+ * Customer-initiated recovery out of a historical 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
@@ -140,8 +132,9 @@ export declare const RESTART_LEAD_DAYS = 2;
  * 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}.
+ * `paused` is now the owner's pause; historical non-payment pauses remain stored
+ * and use their separate recovery path. `cancelled` -> `active` is only
+ * {@link reactivateSubscription}.
  *
  * @beta
  */

package/dist/subscription/subscriptionEngineLifecycle.js

@@ -130,7 +130,7 @@ export function pauseSubscription(input) {
 export function resumeSubscription(input) {
     // 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
+    // a legacy exhausted ladder paused must resume through
     // resumeSubscriptionFromExpiredDunning, which skips the uncollected cycle.
     return changeSubscriptionStatus(input.subscription, "active", input.now, "subscription.resumed", {}, ["paused"]);
 }
@@ -182,19 +182,11 @@ export function reactivateSubscription(input) {
     });
 }
 /**
- * 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`.
+ * Compatibility entry point for an exhausted retry ladder. Exhaustion leaves
+ * the subscription unchanged and emits no pause event. The unpaid cycle stays
+ * available for authorized recovery; it never starts a new cycle implicitly.
+ * Below exhaustion the call still refuses as `dunning_not_exhausted`.
+ * Explicit owner pauses and legacy expired-dunning recovery remain separate.
  *
  * @beta
  */
@@ -206,32 +198,12 @@ export function pauseSubscriptionForExpiredDunning(input) {
     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: [] });
+        return failure("dunning_not_exhausted", "the cycle did not exhaust the retry ladder");
     }
-    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,
-                },
-            }),
-        ],
-    });
+    return success({ subscription: touchSubscription(input.subscription, input.subscription.updatedAt, {}), events: [] });
 }
 /**
- * Customer-initiated recovery out of the non-payment pause.
+ * Customer-initiated recovery out of a historical 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
@@ -413,8 +385,9 @@ function cycleOwnershipError(subscription, cycle) {
  * 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}.
+ * `paused` is now the owner's pause; historical non-payment pauses remain stored
+ * and use their separate recovery path. `cancelled` -> `active` is only
+ * {@link reactivateSubscription}.
  *
  * @beta
  */

package/docs/SUBSCRIPTION_ENGINE.md

@@ -137,9 +137,9 @@ there is none. `DEFAULT_CYCLE_RETRY_CADENCE` ships `backoffHours: [24, 72, 168]`
 ladder in place, and injectable so a deployment can publish its own.
 
 Asking for the next slot **is** the decision. `null` means only that no next
-retry is scheduled; it is a pause signal only after the rung budget is
-exhausted. Class termination before exhaustion leaves the subscription active
-and must not be treated as exhaustion. The function never answers "the last
+retry is scheduled; neither exhaustion nor class termination pauses the
+subscription. Class termination before exhaustion must not be treated as
+exhaustion. The function never answers "the last
 slot again". Callers must not add their own
 `attempt <= maxRetryAttempts()` guard — a second copy of the budget check is
 exactly how two rails drift apart.
@@ -158,7 +158,7 @@ listed, recognised class that the decision table already refuses can shorten
 the ladder. The SQL retry rail publishes the same singleton, and the parity test
 fails if those two spellings drift.
 
-## The status matrix, and the one non-payment pause
+## The status matrix and dunning continuity
 
 `SUBSCRIPTION_STATUS_TRANSITIONS` is the whole status matrix, frozen:
 
@@ -182,26 +182,23 @@ 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.
 
-**The sanctioned non-payment rule.** Nothing in this engine suspends an active
-subscription for a reason its owner did not choose, except a renewal that
-exhausted the retry ladder. `isDunningLadderExhausted(cycle, cadence?)` holds
-only when the cycle is `payment_failed`, has no `nextRetryAt`, and its
-`retryAttempt` is past `maxRetryAttempts(cadence)`. A deployment with its own
-ladder passes the same cadence to `recordPaymentFailure` and to both dunning
-functions, or they disagree about exhaustion. Both halves are required: a
-class-terminated refusal on rung one also leaves nothing scheduled, and it must
-leave the subscription active. `pauseSubscriptionForExpiredDunning` pauses an
-active subscription when that predicate holds. It records `subscription.paused`
-with reason `payment_failed_expired` and never touches `nextCycleAt`. It refuses
-every other cycle as `dunning_not_exhausted`, and returns a subscription that is
-not active unchanged with no event, so a replay is harmless.
-
-`resumeSubscriptionFromExpiredDunning` is the customer's recovery. It needs a
+**The sanctioned non-payment rule.** Payment failure never pauses an active
+subscription. `isDunningLadderExhausted(cycle, cadence?)` means the cycle is
+`payment_failed`, has no `nextRetryAt`, and is past the last retry rung.
+Pass the same cadence to payment failure and dunning operations.
+`pauseSubscriptionForExpiredDunning` retains its compatibility name and inputs,
+but now returns an exhausted subscription unchanged with no event. It refuses
+non-exhausted cycles as `dunning_not_exhausted`. Exhaustion ends automatic
+retries; authorized recovery may still pay the same cycle. Managed SQL still
+hard-codes exhaustion at rung 4 in its dunning, recovery and due-list guards;
+a custom core cadence does not configure those durable boundaries.
+
+`resumeSubscriptionFromExpiredDunning` is the customer's historical-pause recovery. It needs a
 paused subscription, the exhausted cycle and a payment method, stored or
 supplied. The given cycle becomes `skipped` rather than being charged late.
 Whether the method is chargeable unattended is the host's check, and so is
 skipping any other uncollected cycle the host holds; the SQL boundary does both.
-A subscription this rule paused must not go through plain `resumeSubscription`,
+A subscription the historical rule paused must not go through plain `resumeSubscription`,
 which neither skips the cycle nor moves a stale `nextCycleAt`.
 
 Both restarts put `nextCycleAt` `RESTART_LEAD_DAYS` (two) days out, but never

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlup/core",
-  "version": "0.24.0",
+  "version": "0.26.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

@@ -290,8 +290,8 @@
       "release-gates.json"
     ],
     "baseline": {
-      "version": "0.23.0",
-      "packedBytes": 167815
+      "version": "0.25.0",
+      "packedBytes": 167564
     },
     "browserEntries": {}
   },

package/src/subscription/cycleHardening.ts

@@ -11,10 +11,11 @@
  *   - `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.
+ *     run past the last rung; exhaustion leaves the subscription active.
  *
  * 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".
+ * `null`, which ends automatic retries without pausing the subscription; it never
+ * answers "the last slot again".
  * Callers therefore never need a `attempt <= maxRetryAttempts()` guard of their
  * own — asking for the next slot IS the decision, and a second copy of the
  * budget check is exactly how two rails drift apart.
@@ -146,15 +147,11 @@ export function maxRetryAttempts(
  * 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.
+ * Exhaustion stops automatic retries; it never pauses the subscription.
+ * An absent schedule alone is not exhaustion: a terminating refusal class can
+ * leave no retry on the first rung. Pass the same cadence here and to
+ * `recordPaymentFailure`. Legacy expired-dunning recovery also uses this
+ * predicate to distinguish an exhausted cycle from an early refusal.
  *
  * @beta
  */

package/src/subscription/subscriptionEngineLifecycle.ts

@@ -193,7 +193,7 @@ export function resumeSubscription(input: {
 }): SubscriptionEngineResult<SubscriptionMutationResult> {
   // 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
+  // a legacy exhausted ladder paused must resume through
   // resumeSubscriptionFromExpiredDunning, which skips the uncollected cycle.
   return changeSubscriptionStatus(input.subscription, "active", input.now, "subscription.resumed", {}, ["paused"]);
 }
@@ -263,19 +263,11 @@ export function reactivateSubscription(input: {
 }
 
 /**
- * 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`.
+ * Compatibility entry point for an exhausted retry ladder. Exhaustion leaves
+ * the subscription unchanged and emits no pause event. The unpaid cycle stays
+ * available for authorized recovery; it never starts a new cycle implicitly.
+ * Below exhaustion the call still refuses as `dunning_not_exhausted`.
+ * Explicit owner pauses and legacy expired-dunning recovery remain separate.
  *
  * @beta
  */
@@ -292,35 +284,14 @@ export function pauseSubscriptionForExpiredDunning(input: {
   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",
+      "the cycle did not exhaust the retry ladder",
     );
   }
-  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,
-        },
-      }),
-    ],
-  });
+  return success({ subscription: touchSubscription(input.subscription, input.subscription.updatedAt, {}), events: [] });
 }
 
 /**
- * Customer-initiated recovery out of the non-payment pause.
+ * Customer-initiated recovery out of a historical 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
@@ -551,8 +522,9 @@ function cycleOwnershipError(
  * 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}.
+ * `paused` is now the owner's pause; historical non-payment pauses remain stored
+ * and use their separate recovery path. `cancelled` -> `active` is only
+ * {@link reactivateSubscription}.
  *
  * @beta
  */