@mj-biz-apps/sales-entities 6.2.0 → 6.3.0

package/dist/index.d.ts

@@ -28,6 +28,7 @@ export * from './downstream-seams.js';
  * all apply the same one.
  */
 export * from './product-filter.js';
+export * from './term-start.js';
 /**
  * The close lock's field rule, shared by `DealEntityServer.Save()` and the Explorer Deal form so the
  * form cannot offer a field the server will refuse. Pinned by integration check CD14.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC;AAE9C;;;;GAIG;AACH,cAAc,+BAA+B,CAAC;AAE9C;;;;;;;;;GASG;AACH,cAAc,eAAe,CAAC;AAE9B;;;;GAIG;AACH,cAAc,oBAAoB,CAAC;AAEnC;;;;GAIG;AACH,cAAc,kBAAkB,CAAC;AAEjC;;;GAGG;AACH,cAAc,cAAc,CAAC;AAE7B;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAC5C;AACD,cAAc,0BAA0B,CAAC;AAEzC,wFAAwF;AACxF,cAAc,qCAAqC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC;AAE9C;;;;GAIG;AACH,cAAc,+BAA+B,CAAC;AAE9C;;;;;;;;;GASG;AACH,cAAc,eAAe,CAAC;AAE9B;;;;GAIG;AACH,cAAc,oBAAoB,CAAC;AAEnC;;;;GAIG;AACH,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAE7B;;;GAGG;AACH,cAAc,cAAc,CAAC;AAE7B;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAC5C;AACD,cAAc,0BAA0B,CAAC;AAEzC,wFAAwF;AACxF,cAAc,qCAAqC,CAAC"}

package/dist/index.js

@@ -28,6 +28,7 @@ export * from './downstream-seams.js';
  * all apply the same one.
  */
 export * from './product-filter.js';
+export * from './term-start.js';
 /**
  * The close lock's field rule, shared by `DealEntityServer.Save()` and the Explorer Deal form so the
  * form cannot offer a field the server will refuse. Pinned by integration check CD14.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC;AAE9C;;;;GAIG;AACH,cAAc,+BAA+B,CAAC;AAE9C;;;;;;;;;GASG;AACH,cAAc,eAAe,CAAC;AAE9B;;;;GAIG;AACH,cAAc,oBAAoB,CAAC;AAEnC;;;;GAIG;AACH,cAAc,kBAAkB,CAAC;AAEjC;;;GAGG;AACH,cAAc,cAAc,CAAC;AAE7B;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB;AACrC,CAAC;AACD,cAAc,0BAA0B,CAAC;AAEzC,wFAAwF;AACxF,cAAc,qCAAqC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC;AAE9C;;;;GAIG;AACH,cAAc,+BAA+B,CAAC;AAE9C;;;;;;;;;GASG;AACH,cAAc,eAAe,CAAC;AAE9B;;;;GAIG;AACH,cAAc,oBAAoB,CAAC;AAEnC;;;;GAIG;AACH,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAE7B;;;GAGG;AACH,cAAc,cAAc,CAAC;AAE7B;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB;AACrC,CAAC;AACD,cAAc,0BAA0B,CAAC;AAEzC,wFAAwF;AACxF,cAAc,qCAAqC,CAAC"}

package/dist/product-filter.d.ts

@@ -82,7 +82,23 @@ export interface ProductLookup {
      * It is a virtual field on orders' Products view, so it costs nothing but a column.
      */
     Company: string | null;
+    /**
+     * Non-null when this product is sold as a subscription — read only for WHETHER it is set, never for
+     * its value. The rule that consumes it lives in `term-start.ts`, with the reasoning.
+     */
+    SubscriptionTypeID: string | null;
 }
+/**
+ * The columns the picker reads, as ONE exported list rather than a literal at the call site.
+ *
+ * WHY IT IS SHARED. `SubscriptionTypeID` is not displayed anywhere — it only decides whether a line
+ * offers a term start (#32). Drop it from the query and every product arrives without it, so no line is
+ * a subscription, no term start appears, and NOTHING reports an error: the screen quietly loses a
+ * feature. The integration check that guards against exactly that (`term-start.TS5`) has to read the
+ * same list the picker reads, or it proves only that its own copy still works — which is the drift this
+ * suite already warns about for hardcoded SKUs and re-typed filters.
+ */
+export declare const PRODUCT_LOOKUP_FIELDS: readonly ["ID", "Name", "SKU", "CompanyID", "Company", "SubscriptionTypeID"];
 /**
  * The filter that decides what a rep may select, as of `asOf`.
  *

package/dist/product-filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"product-filter.d.ts","sourceRoot":"","sources":["../src/product-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,6FAA6F;AAC7F,eAAO,MAAM,gBAAgB,gCAAgC,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB;;;;;;;;OAQG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;;;;;;OAUG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAOnD"}
+{"version":3,"file":"product-filter.d.ts","sourceRoot":"","sources":["../src/product-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,6FAA6F;AAC7F,eAAO,MAAM,gBAAgB,gCAAgC,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB;;;;;;;;OAQG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;;;;;;OAUG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEvB;;;OAGG;IACH,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,8EAmBmB,CAAC;AAiBtD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAOnD"}

package/dist/product-filter.js

@@ -50,6 +50,38 @@
  */
 /** Orders' Products entity. A SOFT reference — no FK crosses the schema boundary (D-SW3). */
 export const E_ORDERS_PRODUCT = 'MJ_BizApps_Orders: Products';
+/**
+ * The columns the picker reads, as ONE exported list rather than a literal at the call site.
+ *
+ * WHY IT IS SHARED. `SubscriptionTypeID` is not displayed anywhere — it only decides whether a line
+ * offers a term start (#32). Drop it from the query and every product arrives without it, so no line is
+ * a subscription, no term start appears, and NOTHING reports an error: the screen quietly loses a
+ * feature. The integration check that guards against exactly that (`term-start.TS5`) has to read the
+ * same list the picker reads, or it proves only that its own copy still works — which is the drift this
+ * suite already warns about for hardcoded SKUs and re-typed filters.
+ */
+export const PRODUCT_LOOKUP_FIELDS = [
+    'ID',
+    'Name',
+    'SKU',
+    // #29: the line's company comes from the product, and the label names the owner so a rep can tell
+    // two same-named products apart. Drop either and the picker stamps undefined or loses the company.
+    'CompanyID',
+    'Company',
+    // #32: decides whether a line offers a term start at all. Drop it and the control silently vanishes
+    // from every line — which is what `term-start.TS5` exists to catch.
+    'SubscriptionTypeID',
+    /**
+     * `as const satisfies` rather than a type ANNOTATION, and the difference is the whole point.
+     *
+     * Annotating this `readonly (keyof ProductLookup)[]` widens `[number]` to `keyof ProductLookup`,
+     * which makes the completeness check below `Exclude<K, K>` — always `never`, always true. Measured:
+     * with the annotation, dropping 'CompanyID' still compiled. `satisfies` checks each member against
+     * the interface without discarding the literal types.
+     */
+];
+const _everyLookupFieldIsRequested = true;
+void _everyLookupFieldIsRequested;
 /**
  * The filter that decides what a rep may select, as of `asOf`.
  *

package/dist/product-filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"product-filter.js","sourceRoot":"","sources":["../src/product-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,6FAA6F;AAC7F,MAAM,CAAC,MAAM,gBAAgB,GAAG,6BAA6B,CAAC;AAqC9D;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAU;IACvC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,cAAc,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;IACxI,OAAO,CACH,oBAAoB;QACpB,mDAAmD,GAAG,KAAK;QAC3D,+CAA+C,GAAG,IAAI,CACzD,CAAC;AACN,CAAC"}
+{"version":3,"file":"product-filter.js","sourceRoot":"","sources":["../src/product-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,6FAA6F;AAC7F,MAAM,CAAC,MAAM,gBAAgB,GAAG,6BAA6B,CAAC;AA2C9D;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACjC,IAAI;IACJ,MAAM;IACN,KAAK;IACL,kGAAkG;IAClG,mGAAmG;IACnG,WAAW;IACX,SAAS;IACT,oGAAoG;IACpG,oEAAoE;IACpE,oBAAoB;IACpB;;;;;;;OAOG;CAC8C,CAAC;AActD,MAAM,4BAA4B,GAAyD,IAAI,CAAC;AAChG,KAAK,4BAA4B,CAAC;AAElC;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAU;IACvC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,cAAc,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;IACxI,OAAO,CACH,oBAAoB;QACpB,mDAAmD,GAAG,KAAK;QAC3D,+CAA+C,GAAG,IAAI,CACzD,CAAC;AACN,CAAC"}

package/dist/term-start.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview The term-start rule for a deal's subscription lines (sales#32).
+ *
+ * WHY THIS IS A MODULE AND NOT THREE METHODS ON THE WORKSPACE COMPONENT. Two of the three decisions
+ * here are the kind that look obviously right and are quietly wrong — which of them applies is decided
+ * by whether a value is *stored* versus *shown*, and those are indistinguishable in a date control on
+ * screen. Kept as pure functions they can be asserted directly by the integration checks, which is the
+ * same shape the discount rules (`DiscountFractionToPercent`) and the picker filter (`ProductFilterFor`)
+ * already have in this package: the rule lives here, the component delegates, the checks prove it.
+ *
+ * ── WHAT SALES IS ACTUALLY DOING HERE ───────────────────────────────────────────────────────────────
+ *
+ * Writing ONE column, `OrderLine.ServicePeriodStart`, and nothing else. The term END is orders' to
+ * compute at confirm from the subscription's own cadence and proration, and sales does not know either.
+ * This app states intent; orders states the term. Guessing an end date here would be sales computing a
+ * commercial term, which is the boundary rule this repo does not cross.
+ *
+ * ── AND WHAT IT DEPENDS ON ──────────────────────────────────────────────────────────────────────────
+ *
+ * As of this writing orders OVERWRITES the column at confirm:
+ * `OrderEntityServer.materializeSubscriptions` ends with "the line's stored service period reflects the
+ * TERM, not what a user typed" and assigns `line.ServicePeriodStart = term.StartDate`, where the term
+ * start comes from `SubscriptionBehavior.ComputeStartDate`. The companion orders issue changes that hook
+ * to honour an explicitly-set value. Until it lands, everything in this module works and survives save
+ * and reload, and the confirmed term still starts on the order date.
+ *
+ * @module @mj-biz-apps/sales-entities
+ */
+import type { ProductLookup } from './product-filter.js';
+/** Either shape a date can arrive in — an entity field holds a `Date`, a `RunView` row can hold a string. */
+export type DateLike = Date | string | null | undefined;
+/**
+ * Whether a product is sold as a subscription.
+ *
+ * ── THE PREDICATE IS ORDERS', NOT OURS ──
+ *
+ * `OrderEntityServer.subscriptionLines` selects the lines that will receive subscriptions with
+ * `ID IN (...) AND SubscriptionTypeID IS NOT NULL` against this same column. Matching it exactly means
+ * a line offering a term start is exactly a line that will receive a term at confirm. Any other test —
+ * a product-type string, a name convention — could drift from that and offer a term start on a line
+ * which never gets one, which reads as a broken promise rather than a field that does nothing.
+ *
+ * A function rather than a bare `!= null` at each call site because the emptiness test is the subtle
+ * part: `RunView`'s `simple` result type returns an absent uniqueidentifier as `null`, but a row read
+ * another way can carry `''`, and `'' != null` is true — which would mark every non-subscription
+ * product as a subscription. Both shapes are rejected here, once.
+ */
+export declare function IsSubscriptionProduct(product: Pick<ProductLookup, 'SubscriptionTypeID'> | null | undefined): boolean;
+/**
+ * Whether a line shows a term start at all.
+ *
+ * Three cases, and the third is the one worth reading:
+ *
+ * · **No product chosen** — nothing to say. A line with no `ProductID` cannot be a subscription, and it
+ *   already blocks the save on its own account (`UnlinkedLineIssues`).
+ * · **Product in the catalogue** — orders' predicate decides, and that is #32's requirement 3 exactly,
+ *   BUT ONLY WHEN NOTHING IS STORED. A stored value short-circuits every case here: a term start that
+ *   exists is always offered, whatever the product turns out to be, so it can be seen and cleared
+ *   rather than governing the line invisibly. That ordering is the fix in the body below, and this
+ *   list described the rule before it — long enough that the next reader implementing requirement 3
+ *   elsewhere would have copied the stranding bug back in.
+ * · **Product NOT in the catalogue** — quoted before it was withdrawn; `ProductLabel` renders it as
+ *   "(no longer offered)". The lookup cannot say whether it was a subscription, and answering `false`
+ *   would HIDE a term start the rep had already set: the value stays in the database, still governs the
+ *   term, and has no control on screen to see or clear it. So the stored value decides — shown if there
+ *   is one, absent if there is not. Nothing is invented for a line that never had one.
+ *
+ * @param hasProduct - Whether the line references a product at all.
+ * @param product - The catalogue row, or null when the product is no longer offered.
+ * @param stored - What the line currently stores in `ServicePeriodStart`.
+ */
+export declare function ShouldOfferTermStart(hasProduct: boolean, product: Pick<ProductLookup, 'SubscriptionTypeID'> | null | undefined, stored: DateLike): boolean;
+/**
+ * The date the control DISPLAYS: the stored term start, or the order date as a default.
+ *
+ * ── THE DEFAULT IS DISPLAYED, NEVER WRITTEN ──
+ *
+ * This is the whole of #32's behaviour, and the two acceptance criteria that look like opposites are
+ * one rule seen twice: with nothing stored the field follows the order date, and the moment a value is
+ * stored it stops following. Writing the default onto the line at load would collapse both into "always
+ * frozen", would make every line dirty just by opening the deal, and would leave "reset to order date"
+ * with nothing to distinguish it from setting today's date by hand.
+ *
+ * ── EMPTINESS, NOT NULLISHNESS ──
+ *
+ * The fallback triggers on {@link IsEmptyDateLike}, deliberately, and NOT on `??`. This read
+ * `stored ?? orderDate` once, which meant it fell back on null and undefined only — and `'' ?? x` is
+ * `''`. `DateLike` explicitly admits `string`, and a cleared `<input type="date">` reports exactly
+ * `''`, so the code produced the outcome the paragraph above rejects: a blank date box captioned
+ * "order date", with no reset button, because `HasExplicitTermStart('')` is false while
+ * `EffectiveTermStart('')` returned the empty string.
+ *
+ * `||` would have fixed that case and taken a legitimate falsy with it. An explicit emptiness test is
+ * cheaper to read than re-deriving which falsy values `DateLike` can hold.
+ */
+export declare function EffectiveTermStart(stored: DateLike, orderDate: DateLike): DateLike;
+/**
+ * Whether the line carries its own term start rather than showing the order date.
+ *
+ * The one thing a date control cannot show by itself, and the reason the workspace prints "order date"
+ * under an inherited value: an inherited default and a deliberately-chosen date look identical on
+ * screen and behave differently the moment the order date moves.
+ */
+export declare function HasExplicitTermStart(stored: DateLike): boolean;
+//# sourceMappingURL=term-start.d.ts.map

package/dist/term-start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"term-start.d.ts","sourceRoot":"","sources":["../src/term-start.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,6GAA6G;AAC7G,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAExD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACjC,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,oBAAoB,CAAC,GAAG,IAAI,GAAG,SAAS,GACtE,OAAO,CAET;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAChC,UAAU,EAAE,OAAO,EACnB,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,oBAAoB,CAAC,GAAG,IAAI,GAAG,SAAS,EACrE,MAAM,EAAE,QAAQ,GACjB,OAAO,CAgCT;AAoBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAElF;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAU9D"}

package/dist/term-start.js

@@ -0,0 +1,137 @@
+/**
+ * Whether a product is sold as a subscription.
+ *
+ * ── THE PREDICATE IS ORDERS', NOT OURS ──
+ *
+ * `OrderEntityServer.subscriptionLines` selects the lines that will receive subscriptions with
+ * `ID IN (...) AND SubscriptionTypeID IS NOT NULL` against this same column. Matching it exactly means
+ * a line offering a term start is exactly a line that will receive a term at confirm. Any other test —
+ * a product-type string, a name convention — could drift from that and offer a term start on a line
+ * which never gets one, which reads as a broken promise rather than a field that does nothing.
+ *
+ * A function rather than a bare `!= null` at each call site because the emptiness test is the subtle
+ * part: `RunView`'s `simple` result type returns an absent uniqueidentifier as `null`, but a row read
+ * another way can carry `''`, and `'' != null` is true — which would mark every non-subscription
+ * product as a subscription. Both shapes are rejected here, once.
+ */
+export function IsSubscriptionProduct(product) {
+    return !!product && String(product.SubscriptionTypeID ?? '').trim().length > 0;
+}
+/**
+ * Whether a line shows a term start at all.
+ *
+ * Three cases, and the third is the one worth reading:
+ *
+ * · **No product chosen** — nothing to say. A line with no `ProductID` cannot be a subscription, and it
+ *   already blocks the save on its own account (`UnlinkedLineIssues`).
+ * · **Product in the catalogue** — orders' predicate decides, and that is #32's requirement 3 exactly,
+ *   BUT ONLY WHEN NOTHING IS STORED. A stored value short-circuits every case here: a term start that
+ *   exists is always offered, whatever the product turns out to be, so it can be seen and cleared
+ *   rather than governing the line invisibly. That ordering is the fix in the body below, and this
+ *   list described the rule before it — long enough that the next reader implementing requirement 3
+ *   elsewhere would have copied the stranding bug back in.
+ * · **Product NOT in the catalogue** — quoted before it was withdrawn; `ProductLabel` renders it as
+ *   "(no longer offered)". The lookup cannot say whether it was a subscription, and answering `false`
+ *   would HIDE a term start the rep had already set: the value stays in the database, still governs the
+ *   term, and has no control on screen to see or clear it. So the stored value decides — shown if there
+ *   is one, absent if there is not. Nothing is invented for a line that never had one.
+ *
+ * @param hasProduct - Whether the line references a product at all.
+ * @param product - The catalogue row, or null when the product is no longer offered.
+ * @param stored - What the line currently stores in `ServicePeriodStart`.
+ */
+export function ShouldOfferTermStart(hasProduct, product, stored) {
+    if (!hasProduct) {
+        return false;
+    }
+    /**
+     * A STORED VALUE IS OFFERED REGARDLESS OF THE PRODUCT, and that ordering is the fix.
+     *
+     * This used to read `product ? IsSubscriptionProduct(product) : !!stored`, so the `stored` fallback
+     * applied only when the product was UNKNOWN. When the product was known and was not a subscription
+     * the answer was `false` no matter what was stored — the exact outcome this function's docstring
+     * says it prevents: "the value stays in the database, still governs the term, and has no control on
+     * screen to see or clear it".
+     *
+     * It is reachable in one click. A rep sets a term start on a subscription line, then re-picks that
+     * row's product as a one-time item. Nothing on either side reconciles the column —
+     * `OrderLineEntity` and `OrderLineEntityServer` never mention `ServicePeriodStart`, and orders'
+     * subscription materialisation only visits lines carrying a `SubscriptionTypeID` — so the value is
+     * written once and then never read, never cleared, and never seen.
+     *
+     * Worse than invisible: orders' confirm bails out of stamping an event line's own service period
+     * with `if (line.ServicePeriodStart || line.ServicePeriodEnd) return;`, and revenue recognition
+     * then throws for want of a service period. A stranded value turns into a failed confirm naming
+     * nothing the rep did.
+     *
+     * `OnProductChange` now clears the column when the newly chosen product is known and is not a
+     * subscription, which stops the stranding at its source. This is the second half: anything stranded
+     * by another route stays visible and clearable rather than silently governing a term.
+     */
+    if (HasExplicitTermStart(stored)) {
+        return true;
+    }
+    return product ? IsSubscriptionProduct(product) : false;
+}
+/**
+ * Is this `DateLike` absent for our purposes?
+ *
+ * Absent means null, undefined, a blank or whitespace-only string, or a Date that does not parse. The
+ * three predicates in this module disagreed about that before — `??` passed `''` through while `!!`
+ * rejected it, so one function said "no term start" while another rendered the empty string — and a
+ * shared test is what stops them drifting again.
+ */
+function IsEmptyDateLike(value) {
+    if (value === null || value === undefined) {
+        return true;
+    }
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime());
+    }
+    return String(value).trim().length === 0;
+}
+/**
+ * The date the control DISPLAYS: the stored term start, or the order date as a default.
+ *
+ * ── THE DEFAULT IS DISPLAYED, NEVER WRITTEN ──
+ *
+ * This is the whole of #32's behaviour, and the two acceptance criteria that look like opposites are
+ * one rule seen twice: with nothing stored the field follows the order date, and the moment a value is
+ * stored it stops following. Writing the default onto the line at load would collapse both into "always
+ * frozen", would make every line dirty just by opening the deal, and would leave "reset to order date"
+ * with nothing to distinguish it from setting today's date by hand.
+ *
+ * ── EMPTINESS, NOT NULLISHNESS ──
+ *
+ * The fallback triggers on {@link IsEmptyDateLike}, deliberately, and NOT on `??`. This read
+ * `stored ?? orderDate` once, which meant it fell back on null and undefined only — and `'' ?? x` is
+ * `''`. `DateLike` explicitly admits `string`, and a cleared `<input type="date">` reports exactly
+ * `''`, so the code produced the outcome the paragraph above rejects: a blank date box captioned
+ * "order date", with no reset button, because `HasExplicitTermStart('')` is false while
+ * `EffectiveTermStart('')` returned the empty string.
+ *
+ * `||` would have fixed that case and taken a legitimate falsy with it. An explicit emptiness test is
+ * cheaper to read than re-deriving which falsy values `DateLike` can hold.
+ */
+export function EffectiveTermStart(stored, orderDate) {
+    return IsEmptyDateLike(stored) ? (orderDate ?? null) : stored;
+}
+/**
+ * Whether the line carries its own term start rather than showing the order date.
+ *
+ * The one thing a date control cannot show by itself, and the reason the workspace prints "order date"
+ * under an inherited value: an inherited default and a deliberately-chosen date look identical on
+ * screen and behave differently the moment the order date moves.
+ */
+export function HasExplicitTermStart(stored) {
+    /**
+     * An UNPARSEABLE value is not an explicit term start.
+     *
+     * `!!new Date('nonsense')` is true, and the formatter applies `getUTCFullYear()` with no NaN guard,
+     * so the field rendered "NaN-NaN-NaN" — which `<input type="date">` rejects and shows blank. The
+     * app then believed the line carried a deliberate term start: reset button shown, hint suppressed,
+     * and no fallback to the order date.
+     */
+    return !IsEmptyDateLike(stored);
+}
+//# sourceMappingURL=term-start.js.map

package/dist/term-start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"term-start.js","sourceRoot":"","sources":["../src/term-start.ts"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CACjC,OAAqE;IAErE,OAAO,CAAC,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,kBAAkB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AACnF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,oBAAoB,CAChC,UAAmB,EACnB,OAAqE,EACrE,MAAgB;IAEhB,IAAI,CAAC,UAAU,EAAE,CAAC;QACd,OAAO,KAAK,CAAC;IACjB,CAAC;IACD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,IAAI,oBAAoB,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,OAAO,OAAO,CAAC,CAAC,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAC5D,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,eAAe,CAAC,KAAe;IACpC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxC,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,IAAI,KAAK,YAAY,IAAI,EAAE,CAAC;QACxB,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAgB,EAAE,SAAmB;IACpE,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;AAClE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAgB;IACjD;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mj-biz-apps/sales-entities",
   "type": "module",
-  "version": "6.2.0",
+  "version": "6.3.0",
   "description": "MJ BizApps Sales Entity Subclasses",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",