@mj-biz-apps/orders-core-entities-server 5.26.0 → 5.28.0

package/dist/OrderEntityServer.js

@@ -61,12 +61,12 @@ import { ResolveDueDate } from './PaymentTermsBehavior.js';
 import { PaymentTermsChangeGranted } from './PaymentTermsSanction.js';
 import { ExplainShortfalls, ScheduleShortfalls } from './PaymentScheduleBehavior.js';
 import { IssueInstalment } from './IssueInstalmentInvoiceOperation.js';
-import { ORDER_HEADER_PAYMENT_SCHEDULE_ENTITY } from './entity-names.js';
+import { ORDER_HEADER_PAYMENT_SCHEDULE_ENTITY, SUBSCRIPTION_FAMILY_ENTITY } from './entity-names.js';
 import { CheckOrderBillToName, LoadBillToName } from './RailCustomerNameLimit.js';
 import { Today, LineGross, LoadOrdersEngine, NetAfterDiscount, OrderPricingService, OrdersEngine, WriteAdjustments, WriteCharges } from '@mj-biz-apps/orders-entities';
 const CUSTOMER_PAYMENT_TERMS_ENTITY = 'MJ_BizApps_Orders: Customer Payment Terms';
 const ORDER_COMPANY_POLICY_ENTITY = 'MJ_BizApps_Orders: Order Company Policies';
-import { SubscriptionBehavior, ResolveSubscriptionTypeID, SubscriptionTypeRulesFrom, } from './SubscriptionBehavior.js';
+import { SubscriptionBehavior, ResolveSubscriptionTypeID, SubscriptionTypeRulesFrom, OverlappingCoverage, } from './SubscriptionBehavior.js';
 const ORDER_ENTITY = 'MJ_BizApps_Orders: Order Headers';
 const CHARGE_TYPE_ENTITY = 'MJ_BizApps_Orders: Charge Types';
 // bizapps-common names its entities with DOTS, not the underscores the other apps use.
@@ -114,6 +114,8 @@ const DEPENDENT_ROW_CAP = 1000;
  * same failure shape: a silent miss that looks like missing data rather than a key mismatch.
  */
 const uuidKey = (id) => (id ?? '').toLowerCase();
+/** How live a subscription is, lowest first: the order a re-purchase prefers among several. */
+const subscriptionStatusRank = (status) => status === 'Active' || status === 'Trialing' ? 0 : status === 'Paused' ? 1 : status === 'Canceled' ? 2 : 3;
 /**
  * Stands in for a subscription an EARLIER LINE OF THIS ORDER is about to create.
  *
@@ -131,6 +133,8 @@ let OrderEntityServer = class OrderEntityServer extends OrderHeaderEntity {
         super(...arguments);
         /** Price decompositions produced during this save, written once the lines have IDs (D69). */
         this._priceComponents = new Map();
+        /** Lines the renewal pass priced, with the price it wrote; see {@link MarkRenewalPriced}. */
+        this._renewalPricedLines = new Map();
         /** Why a line owes no tax, by line index — written as a zero-amount component (D73). */
         this._taxReasons = new Map();
         this._manualDiscounts = [];
@@ -174,6 +178,27 @@ let OrderEntityServer = class OrderEntityServer extends OrderHeaderEntity {
     PaymentTermsChangeSanctioned() {
         return PaymentTermsChangeGranted(this);
     }
+    /**
+     * Record that the renewal pass priced this line (golive #304).
+     *
+     * A renewal is priced from the prior term, not today's list: a lapsed discount, a grandfathered
+     * price raised by the annual increase. That can sit below the engine's price, and it is the
+     * price finance chose, not a concession someone typed. While the line still carries the price
+     * the pass wrote, the concession gate and the below-engine review treat it as engine-priced.
+     * Change the price and both judge it as usual.
+     */
+    MarkRenewalPriced(line) {
+        this._renewalPricedLines.set(line, Number(line.UnitPrice));
+    }
+    /** True for a line the renewal pass priced whose price is unchanged; matched by entity or saved ID. */
+    isUneditedRenewalPrice(line) {
+        for (const [marked, price] of this._renewalPricedLines) {
+            const same = marked === line || (!!line.ID && marked.IsSaved && marked.ID.toLowerCase() === String(line.ID).toLowerCase());
+            if (same)
+                return Math.abs(Number(line.UnitPrice ?? 0) - price) < 0.005;
+        }
+        return false;
+    }
     // `PromotionCodes` is not declared here any more. It is a COMPANION on the shared subclass, so
     // the browser has it too — which is the entire point: a code typed on screen used to be priced
     // into the preview and then dropped at confirm, because only the server could hold one.
@@ -470,6 +495,11 @@ let OrderEntityServer = class OrderEntityServer extends OrderHeaderEntity {
                 await this.Lines.Load();
             }
             await this.expandBundles();
+            // EVERY LINE'S PRODUCT IN THE CATALOG CACHE, reloaded once if any is missing (golive #301).
+            // Subscription decisions, the company stamp, dimension tags and booking all read the
+            // product from `OrdersEngine`; a product written outside this process since it started
+            // was invisible to all of them. One reload here serves the whole save.
+            await OrdersEngine.Instance.EnsureProducts(this.Lines.Items.map((l) => l.ProductID), this.ContextCurrentUser, this.ProviderToUse);
             const decisions = booking ? await this.decideSubscriptions() : new Map();
             // Ahead of pricing, so an ordinary line on a reversal order is taxed at the address the
             // order will show. Reversal lines take their tax from their origin and ignore it.
@@ -811,7 +841,9 @@ let OrderEntityServer = class OrderEntityServer extends OrderHeaderEntity {
             Quantity: line.Quantity,
             UnitPrice: line.UnitPrice,
             ProductPriceID: line.ProductPriceID,
-            PriceStated: line.IsSaved || line.GetFieldByName('UnitPrice')?.Dirty === true || (line.UnitPrice ?? 0) > 0,
+            // A renewal line's price is the renewal pass's own decision (golive #304), not a stated one.
+            PriceStated: !this.isUneditedRenewalPrice(line) &&
+                (line.IsSaved || line.GetFieldByName('UnitPrice')?.Dirty === true || (line.UnitPrice ?? 0) > 0),
             LineTotalNet: line.IsRollupParent ? 0 : this.pendingLineNet(line),
         }));
         const problems = await FindUnapprovedConcessions(this.IsSaved ? this.ID : null, lines, true, this.ProviderToUse, user);
@@ -847,7 +879,7 @@ let OrderEntityServer = class OrderEntityServer extends OrderHeaderEntity {
                 Quantity: line.Quantity,
                 UnitPrice: line.UnitPrice,
                 ProductPriceID: line.ProductPriceID,
-                PriceStated: true,
+                PriceStated: !this.isUneditedRenewalPrice(line),
                 CompanyID: line.CompanyID,
             })),
             BusinessDay: () => BusinessDay(provider, user),
@@ -2378,7 +2410,7 @@ let OrderEntityServer = class OrderEntityServer extends OrderHeaderEntity {
             }
             const subscriptionID = decision.Action === 'CreateNew'
                 ? await this.createSubscription(line, product, rules, decision, decided.Subscriber, options)
-                : await this.touchExistingSubscription(decision, !!line.RenewsSubscriptionID, options, DisplacedStartEventData(line.ID, decided.Decision, decided.RequestedStart));
+                : await this.touchExistingSubscription(decision, !!line.RenewsSubscriptionID, options, DisplacedStartEventData(line.ID, decided.Decision, decided.RequestedStart), line.RenewsSubscriptionID ? { ProductID: product.ID, SubscriptionTypeID: rules.ID } : undefined);
             // Remember it so a later line for the same subscription resolves above.
             if (decision.Action === 'CreateNew')
                 createdByDedupeKey.set(decided.DedupeKey, subscriptionID);
@@ -2458,14 +2490,32 @@ let OrderEntityServer = class OrderEntityServer extends OrderHeaderEntity {
         }
         return out;
     }
+    /**
+     * The subscription lines of this draft whose terms overlap coverage in their family, and what
+     * confirm will do with each (golive #276). Writes nothing.
+     *
+     * Runs the same decision pass confirm runs, over the SAVED lines. Lines a bundle would add at
+     * confirm are not expanded here, so a band sold inside a bundle is caught at confirm only.
+     */
+    async PreviewCoverageOverlaps() {
+        if (this.IsSaved && !this.Lines.IsLoaded)
+            await this.Lines.Load();
+        const out = [];
+        await this.decideSubscriptions(out);
+        return out;
+    }
     /**
      * Evaluate the subscription rules for every pending line, BEFORE any of them is inserted.
      *
      * Pure with respect to this app's tables — it reads the catalog and any existing subscription,
      * then asks the behaviour what to do. Nothing is written, so a rules rejection aborts the
      * confirm before a single line exists.
+     *
+     * `preview` turns refusals into answers: a line the rules reject is skipped, and every line
+     * whose term overlaps coverage in its family is collected there instead of throwing. That is
+     * how `Orders.CheckCoverageOverlap` asks the same question confirm does without confirming.
      */
-    async decideSubscriptions() {
+    async decideSubscriptions(preview) {
         const out = new Map();
         const subLines = await this.subscriptionLines([...this.Lines.Items]);
         if (subLines.length === 0)
@@ -2478,6 +2528,10 @@ let OrderEntityServer = class OrderEntityServer extends OrderHeaderEntity {
         // ever see the database, so two lines for one subscription both decide
         // "create" — see PENDING_SIBLING_ID.
         const pendingSiblings = new Map();
+        // The same, for other BANDS: terms earlier lines of this order will create, keyed by
+        // family and holder, so two bands on one order are checked against each other too.
+        const pendingFamily = new Map();
+        const familyNames = await this.loadFamilyNames(subLines.map((s) => s.product.SubscriptionFamilyID));
         // The order's booking day, as a calendar day (#209). `Decide` reduces it with `utcDay` and
         // the settled term reaches `SubscriptionTerm.StartDate`/`EndDate`, both `DATE NOT NULL`, so
         // an instant taken at 9 PM Eastern would start coverage tomorrow.
@@ -2493,13 +2547,15 @@ let OrderEntityServer = class OrderEntityServer extends OrderHeaderEntity {
             const behavior = this.behaviorFor(rules);
             let subscriber = await this.withInferredOrganization(this.resolveSubscriber(line));
             const identity = behavior.DedupeIdentity(rules, subscriber);
+            const match = behavior.DedupeMatch(rules, subscriber);
             const dedupeKey = `${product.ID}|${identity.OrganizationID ?? ''}|${identity.PersonID ?? ''}`;
             // An explicitly named subscription wins; then a sibling line of THIS order;
             // then one already in the database for this subscriber and product (D62).
             const existing = line.RenewsSubscriptionID
                 ? await this.loadSubscriptionState(`ID='${line.RenewsSubscriptionID}'`)
                 : (pendingSiblings.get(dedupeKey) ??
-                    (await this.findExistingSubscription(product.ID, identity)));
+                    (match.OrNoPerson ? pendingSiblings.get(`${product.ID}|${identity.OrganizationID}|`) : undefined) ??
+                    (await this.findExistingSubscription(product.ID, match)));
             // NAMING a subscription IS the statement of who the subscriber is. Requiring the line to
             // restate it would make renewing a seat impossible without repeating the person, and any
             // mismatch between the two would be a silent contradiction. The target wins.
@@ -2537,16 +2593,61 @@ let OrderEntityServer = class OrderEntityServer extends OrderHeaderEntity {
                 RequestedAction: line.SubscriptionAction,
             });
             if (decision.Action === 'Reject') {
+                if (preview)
+                    continue;
                 // A rules violation fails the WHOLE confirm — booking is all-or-none, and a
                 // silently-dropped subscription would leave a paid-for line with no coverage.
                 throw new Error(`Order line ${line.LineNumber} (${product.Name}) cannot be subscribed: ${decision.RejectReason}`);
             }
+            // ANOTHER BAND of the same offering (golive #276). The lookup above matches on the
+            // product, so a holder with coverage under a sibling band found nothing and a second
+            // subscription for the same dates was created and billed. A renewal names its target
+            // outright, so it continues that subscription and is not checked.
+            if (decision.Term && product.SubscriptionFamilyID && !line.RenewsSubscriptionID) {
+                const familyKey = `${uuidKey(product.SubscriptionFamilyID)}|${identity.OrganizationID ?? ''}|${identity.PersonID ?? ''}`;
+                const noPersonKey = `${uuidKey(product.SubscriptionFamilyID)}|${identity.OrganizationID ?? ''}|`;
+                const siblings = [
+                    ...(pendingFamily.get(familyKey) ?? []),
+                    ...(match.OrNoPerson ? (pendingFamily.get(noPersonKey) ?? []) : []),
+                ].filter((s) => !UUIDsEqual(s.ProductID, product.ID));
+                const overlaps = OverlappingCoverage([...siblings, ...(await this.loadFamilyCoverage(product, match, decision.Term.StartDate))], decision.Term.StartDate, decision.Term.EndDate);
+                const verdict = behavior.DecideCoverageOverlap({
+                    Rules: rules,
+                    Family: familyNames.get(uuidKey(product.SubscriptionFamilyID)) ?? product.SubscriptionFamilyID,
+                    ProductName: product.Name,
+                    Overlaps: overlaps,
+                    Acknowledged: !!line.AcknowledgesCoverageOverlap,
+                });
+                if (preview) {
+                    if (verdict.Outcome !== 'None')
+                        preview.push({ Line: line, Decision: verdict, Overlaps: overlaps });
+                }
+                else if (verdict.Outcome === 'Refused' || verdict.Outcome === 'NeedsAck') {
+                    throw new Error(`Order line ${line.LineNumber} (${product.Name}) cannot be confirmed: ${verdict.Message}`);
+                }
+                else if (verdict.Outcome !== 'None') {
+                    LogStatus(`Order ${this.OrderNumber ?? this.ID} line ${line.LineNumber}: ${verdict.Message}`);
+                }
+                pendingFamily.set(familyKey, [
+                    ...(pendingFamily.get(familyKey) ?? []),
+                    {
+                        ProductID: product.ID,
+                        SubscriptionID: null,
+                        SubscriptionNumber: null,
+                        ProductName: product.Name,
+                        StartDate: decision.Term.StartDate,
+                        EndDate: decision.Term.EndDate,
+                        ConcurrencyMode: rules.ConcurrencyMode,
+                        SubscriptionTypeCode: rules.Code,
+                    },
+                ]);
+            }
             // A stated start that existing coverage displaced. NOT an error: extending a
             // subscription mid-term and stating where the new term begins are both reasonable,
             // and only one of them can win — coverage cannot overlap or gap. Reported rather than
             // swallowed so the date's disappearance is traceable to a rule instead of looking
             // like the field was never saved.
-            if (decision.StartOverrideIgnored && decision.Term && requestedStart) {
+            if (!preview && decision.StartOverrideIgnored && decision.Term && requestedStart) {
                 LogStatus(`Order ${this.OrderNumber ?? this.ID} line ${line.LineNumber} (${product.Name}): the term start ` +
                     `${requestedStart.toISOString().slice(0, 10)} stated on the line was not used. This line ` +
                     `extends an existing subscription, so its term begins the day after current coverage ends — ` +
@@ -2621,7 +2722,7 @@ let OrderEntityServer = class OrderEntityServer extends OrderHeaderEntity {
         // would be filed against the wrong organization on the order.
         const asOf = await CalendarDayOrToday(this.OrderDate, this.ProviderToUse, this.ContextCurrentUser);
         const inferred = await this.organizationAsOf(subscriber.PersonID, asOf);
-        return inferred ? { ...subscriber, OrganizationID: inferred } : subscriber;
+        return inferred ? { ...subscriber, OrganizationID: inferred, OrganizationInferred: true } : subscriber;
     }
     /**
      * The organization a person belonged to AS OF the order date (D64).
@@ -2673,18 +2774,26 @@ let OrderEntityServer = class OrderEntityServer extends OrderHeaderEntity {
             return [];
         const provider = this.ProviderToUse;
         const user = this.ContextCurrentUser;
-        await LoadOrdersEngine(provider, user);
+        await OrdersEngine.Instance.EnsureProducts(lines.map((l) => l.ProductID), user, provider);
         const products = new Map();
         for (const line of lines) {
-            const p = OrdersEngine.Instance.ProductByID(line.ProductID);
-            if (!p)
+            if (!line.ProductID)
                 continue;
+            const p = OrdersEngine.Instance.ProductByID(line.ProductID);
+            // Not skipped: a skipped line was silently treated as no subscription, so it got no term
+            // and no service period (golive #301).
+            if (!p) {
+                throw new Error(`Order line ${line.LineNumber}: product ${line.ProductID} was not found in the product catalog, ` +
+                    `even after reloading it from the database.`);
+            }
             products.set(uuidKey(p.ID), {
                 ID: p.ID,
                 Name: p.Name,
                 SubscriptionTypeID: p.SubscriptionTypeID,
                 ProductTypeID: p.ProductTypeID,
                 RevenueRecognitionTypeID: p.RevenueRecognitionTypeID,
+                CompanyID: p.CompanyID,
+                SubscriptionFamilyID: p.SubscriptionFamilyID,
             });
         }
         if (products.size === 0)
@@ -2804,32 +2913,155 @@ let OrderEntityServer = class OrderEntityServer extends OrderHeaderEntity {
      * would be a guess, and would pick the wrong one whenever a customer holds two subscriptions to
      * the same product under an `AllowMultiple` type.
      */
-    async findExistingSubscription(productID, identity) {
-        // Match on exactly the axes the BenefitModel says define a duplicate. An org-members type
-        // ignores the person entirely (one company membership, however many employees); a seat type
-        // matches BOTH, so two seats for two people never collide.
-        const clauses = [];
-        clauses.push(identity.OrganizationID
-            ? `HolderOrganizationID='${identity.OrganizationID}'`
-            : `HolderOrganizationID IS NULL`);
-        clauses.push(identity.PersonID ? `BeneficiaryPersonID='${identity.PersonID}'` : `BeneficiaryPersonID IS NULL`);
-        if (!identity.OrganizationID && !identity.PersonID)
+    async findExistingSubscription(productID, match) {
+        const holder = this.holderFilter(match);
+        if (!holder)
             return null;
-        return this.loadSubscriptionState(`ProductID='${productID}' AND ${clauses.join(' AND ')}`);
+        const person = match.PersonID === 'Any' ? null : match.PersonID;
+        return this.loadSubscriptionState(`ProductID='${productID}' AND ${holder}`, person);
+    }
+    /**
+     * The subscription filter for a dedupe match, or null when it names nobody.
+     *
+     * Match on exactly the axes the BenefitModel says define a duplicate (`DedupeMatch`). An
+     * org-held type ignores the stored person entirely (one company membership, however many
+     * employees, whoever the order named as its contact); a seat type matches BOTH, so two seats
+     * for two people never collide.
+     */
+    holderFilter(match) {
+        if (!match.OrganizationID && !match.PersonID)
+            return null;
+        const org = match.OrganizationID
+            ? `HolderOrganizationID='${RequireUUID(match.OrganizationID, 'HolderOrganizationID')}'`
+            : `HolderOrganizationID IS NULL`;
+        if (match.PersonID === 'Any')
+            return org;
+        if (!match.PersonID)
+            return `${org} AND BeneficiaryPersonID IS NULL`;
+        const person = `BeneficiaryPersonID='${RequireUUID(match.PersonID, 'BeneficiaryPersonID')}'`;
+        return match.OrNoPerson
+            ? `${org} AND (${person} OR BeneficiaryPersonID IS NULL)`
+            : `${org} AND ${person}`;
+    }
+    /** Family names by ID, for the overlap message. One read for every family on the order. */
+    async loadFamilyNames(ids) {
+        const unique = [...new Set(ids.filter((id) => !!id).map(uuidKey))];
+        if (unique.length === 0)
+            return new Map();
+        const rv = new RunView(this.ProviderToUse);
+        const list = RequireUUIDs(unique, 'SubscriptionFamilyID').map((id) => `'${id}'`).join(',');
+        const res = await rv.RunView({
+            EntityName: SUBSCRIPTION_FAMILY_ENTITY,
+            ExtraFilter: `ID IN (${list})`,
+            Fields: ['ID', 'Code', 'Name'],
+            ResultType: 'simple',
+        }, this.ContextCurrentUser);
+        if (!res?.Success)
+            throw new Error(`Could not read subscription families: ${res?.ErrorMessage}`);
+        return new Map(res.Results.map((f) => [uuidKey(f.ID), `${f.Name} (${f.Code})`]));
+    }
+    /**
+     * Terms that cover this holder under OTHER bands of the product's family and end on or after
+     * `start` (golive #276). Terms after `end` are included so the caller can say when coverage
+     * runs out.
+     *
+     * Bands are the family's other products in the product's own company. A subscription counts
+     * unless it is Migrated, and its terms count unless they are Canceled or Lapsed. A Canceled
+     * subscription still counts: cancelling stamps one term and leaves the subscription's access
+     * running to `Subscription.EndDate`, so its Canceled term counts through that date, and any
+     * term it did not stamp counts in full.
+     */
+    async loadFamilyCoverage(product, match, start) {
+        const holder = this.holderFilter(match);
+        const familyID = product.SubscriptionFamilyID;
+        if (!holder || !familyID)
+            return [];
+        // The engine caches every product, active or not — a discontinued band still has holders.
+        const bands = new Map(OrdersEngine.Instance.Products.filter((p) => UUIDsEqual(p.SubscriptionFamilyID, familyID) &&
+            UUIDsEqual(p.CompanyID, product.CompanyID) &&
+            !UUIDsEqual(p.ID, product.ID)).map((p) => [uuidKey(p.ID), p.Name]));
+        if (bands.size === 0)
+            return [];
+        const rv = new RunView(this.ProviderToUse);
+        const bandIDs = RequireUUIDs([...bands.keys()], 'ProductID').map((id) => `'${id}'`).join(',');
+        const subs = await rv.RunView({
+            EntityName: SUBSCRIPTION_ENTITY,
+            ExtraFilter: `ProductID IN (${bandIDs}) AND ${holder} AND Status <> 'Migrated'`,
+            Fields: ['ID', 'SubscriptionNumber', 'ProductID', 'SubscriptionTypeID', 'Status', 'EndDate'],
+            ResultType: 'simple',
+            BypassCache: true,
+        }, this.ContextCurrentUser);
+        if (!subs?.Success) {
+            throw new Error(`Could not read this holder's other subscriptions in the product's family: ${subs?.ErrorMessage}`);
+        }
+        if (subs.Results.length === 0)
+            return [];
+        const byID = new Map(subs.Results.map((s) => [uuidKey(s.ID), s]));
+        const subIDs = RequireUUIDs(subs.Results.map((s) => s.ID), 'SubscriptionID').map((id) => `'${id}'`).join(',');
+        const day = (d) => d.toISOString().slice(0, 10);
+        const terms = await rv.RunView({
+            EntityName: SUBSCRIPTION_TERM_ENTITY,
+            ExtraFilter: `SubscriptionID IN (${subIDs}) AND Status <> 'Lapsed' AND EndDate >= '${day(start)}'`,
+            Fields: ['SubscriptionID', 'StartDate', 'EndDate', 'Status'],
+            ResultType: 'simple',
+            BypassCache: true,
+        }, this.ContextCurrentUser);
+        if (!terms?.Success) {
+            throw new Error(`Could not read the terms of this holder's other subscriptions in the product's family: ${terms?.ErrorMessage}`);
+        }
+        const out = [];
+        for (const t of terms.Results) {
+            const sub = byID.get(uuidKey(t.SubscriptionID));
+            if (!sub)
+                continue;
+            let endDate = new Date(t.EndDate);
+            if (t.Status === 'Canceled') {
+                // Only a cancelled subscription's own access window keeps a Canceled term alive.
+                if (sub.Status !== 'Canceled' || !sub.EndDate)
+                    continue;
+                const accessEnd = new Date(sub.EndDate);
+                if (accessEnd.getTime() < endDate.getTime())
+                    endDate = accessEnd;
+            }
+            const type = OrdersEngine.Instance.SubscriptionTypeByID(sub.SubscriptionTypeID);
+            if (!type) {
+                throw new Error(`Subscription ${sub.SubscriptionNumber} names a subscription type that was not found.`);
+            }
+            const rules = SubscriptionTypeRulesFrom(type);
+            out.push({
+                SubscriptionID: t.SubscriptionID,
+                SubscriptionNumber: sub.SubscriptionNumber ?? null,
+                ProductName: bands.get(uuidKey(sub.ProductID)) ?? 'another band',
+                StartDate: new Date(t.StartDate),
+                EndDate: endDate,
+                ConcurrencyMode: rules.ConcurrencyMode,
+                SubscriptionTypeCode: rules.Code,
+            });
+        }
+        return out;
     }
-    /** Load a subscription plus the end and number of its latest term, by whatever filter. */
-    async loadSubscriptionState(filter) {
+    /**
+     * Load a subscription plus the end and number of its latest term, by whatever filter.
+     *
+     * When the filter matches several, the most live one wins: Active or Trialing, then Paused,
+     * then Canceled, then the rest; among equals, one stored for `personID`, then the newest.
+     */
+    async loadSubscriptionState(filter, personID) {
         const rv = new RunView(this.ProviderToUse);
         const res = await rv.RunView({
             EntityName: SUBSCRIPTION_ENTITY,
             ExtraFilter: filter,
             Fields: ['ID', 'Status', 'HolderOrganizationID', 'BeneficiaryPersonID'],
             OrderBy: '__mj_CreatedAt DESC',
-            MaxRows: 1,
             ResultType: 'simple',
             BypassCache: true,
         }, this.ContextCurrentUser);
-        const sub = res?.Results?.[0];
+        // An org-held match ignores the stored person, so an org can match several, and a newer
+        // canceled one must not hide one still running or paused. Rows arrive newest first and the
+        // sort is stable, so the newest wins among equals.
+        const rows = [...(res?.Results ?? [])].sort((a, b) => subscriptionStatusRank(a.Status) - subscriptionStatusRank(b.Status) ||
+            Number(!UUIDsEqual(a.BeneficiaryPersonID, personID)) - Number(!UUIDsEqual(b.BeneficiaryPersonID, personID)));
+        const sub = rows[0];
         if (!sub)
             return null;
         const terms = await rv.RunView({
@@ -2921,10 +3153,25 @@ let OrderEntityServer = class OrderEntityServer extends OrderHeaderEntity {
                 `${event.LatestResult?.CompleteMessage ?? 'unknown error'}`);
         }
     }
-    /** Extension or reactivation — the term is what changes; the subscription just re-activates. */
-    async touchExistingSubscription(decision, isRenewal, options, displacedStart) {
+    /**
+     * Extension or reactivation — the term is what changes; the subscription just re-activates.
+     *
+     * `renewedOnto` is the product a renewal line names. When it is not the subscription's product,
+     * the subscription moved to a successor at renewal (golive #304), and from this term on it is a
+     * subscription to the successor: its product and type follow, so the next renewal, entitlement
+     * checks and reports all read the product the customer now holds.
+     */
+    async touchExistingSubscription(decision, isRenewal, options, displacedStart, renewedOnto) {
         const provider = this.ProviderToUse;
         const sub = await provider.GetEntityObject(SUBSCRIPTION_ENTITY, CompositeKey.FromID(decision.SubscriptionID), this.ContextCurrentUser);
+        if (renewedOnto && sub.ProductID.toLowerCase() !== renewedOnto.ProductID.toLowerCase()) {
+            sub.ProductID = renewedOnto.ProductID;
+            sub.SubscriptionTypeID = renewedOnto.SubscriptionTypeID;
+            if (!(await sub.Save(options))) {
+                throw new Error(`Failed to move subscription ${sub.SubscriptionNumber} onto its successor product: ` +
+                    `${sub.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            }
+        }
         if (decision.Action === 'Reactivate') {
             sub.Status = 'Active';
             sub.CanceledAt = null;
@@ -3160,7 +3407,7 @@ let OrderEntityServer = class OrderEntityServer extends OrderHeaderEntity {
         if (!rows.Success) {
             throw new Error(`Could not read the payment schedule for order ${this.OrderNumber}: ${rows.ErrorMessage ?? 'unknown error'}`);
         }
-        const shortfalls = ScheduleShortfalls(rows.Results ?? [], lines.map((l) => ({ CompanyID: String(l.CompanyID), LineTotalGross: Number(l.LineTotalGross ?? 0) })));
+        const shortfalls = ScheduleShortfalls(rows.Results ?? [], lines.map((l) => ({ CompanyID: String(l.CompanyID), LineTotalGross: Number(l.LineTotalGross ?? 0) })), String(this.CompanyID ?? ''));
         if (!shortfalls.length)
             return rows.Results ?? [];
         const names = new Map((rows.Results ?? []).map((r) => [String(r.CompanyID).toLowerCase(), r.Company ?? r.CompanyID]));