@mj-biz-apps/contracts-entities 0.1.0

package/LICENSE

@@ -0,0 +1,183 @@
+Business Source License 1.1
+
+License text copyright (c) 2024 MariaDB plc, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB plc.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Blue Cypress, Inc.
+
+Licensed Work:        MemberJunction.
+                      The Licensed Work is (c) 2023-2026 Blue Cypress, Inc.
+
+Additional Use Grant: Subject to the terms of this License, Licensor grants
+                      you the following additional rights to make Production
+                      Use of the Licensed Work.
+
+                      1. Internal Use
+
+                      You may make production use of the Licensed Work for
+                      your own internal business or organizational operations.
+
+                      2. Nonprofit Use
+
+                      If you are a Nonprofit, you may make production use of
+                      the Licensed Work for the operations and activities of
+                      your Organizational Family.
+
+                      3. MemberJunction Certified Program Use
+
+                      If you are authorized by Licensor under the
+                      MemberJunction Certified Program to provide professional
+                      services using the Licensed Work, you may make
+                      production use of the Licensed Work in providing such
+                      professional services to a client, provided that:
+
+                      (a) the Licensed Work is deployed in, and the applicable
+                      production use occurs within, an environment owned,
+                      leased, licensed, subscribed to, or otherwise controlled
+                      by that client; and
+
+                      (b) the production use is for that client's own internal
+                      business or organizational operations or is otherwise
+                      independently permitted to that client under this
+                      Additional Use Grant.
+
+                      4. Definitions Applicable to the Additional Use Grant
+
+                      "Affiliate" means, with respect to a specified Person,
+                      any other Person that directly or indirectly Controls,
+                      is Controlled by, or is under common Control with such
+                      specified Person.
+
+                      "Control" (including the terms "Controls," "Controlled
+                      by," and "under common Control with") means the direct
+                      or indirect possession of the power to direct or cause
+                      the direction of the management and policies of a
+                      Person, whether through ownership of voting interests,
+                      by contract, or otherwise.
+
+                      "Organizational Family" means, with respect to a Person,
+                      (a) such Person and its Affiliates, and (b) any
+                      nonprofit organization, governmental entity, chapter,
+                      division, local affiliate, regional affiliate, state
+                      affiliate, national affiliate, or other entity that is
+                      formally affiliated with such Person through governing
+                      documents, a charter, bylaws, a membership agreement, or
+                      another written organizational instrument, and is
+                      recognized under such documents as part of the same
+                      organizational structure.
+
+                      "Nonprofit" means a Person recognized by the Internal
+                      Revenue Service as exempt from federal income taxation
+                      under Section 501(c)(3), 501(c)(4), 501(c)(5), or
+                      501(c)(6) of the Internal Revenue Code, or a foreign
+                      organization recognized under substantially equivalent
+                      laws.
+
+                      A Person claiming eligibility as a Nonprofit shall, upon
+                      Licensor's reasonable request, provide documentation
+                      reasonably sufficient to demonstrate that it qualifies
+                      as a Nonprofit. If such Person materially misrepresents,
+                      or is unable to demonstrate, its qualification as a
+                      Nonprofit, the rights granted to such Person under
+                      Section 2 of this Additional Use Grant shall terminate.
+
+                      "MemberJunction Certified Program" means Licensor's
+                      then-current program for certifying and authorizing a
+                      Person to provide professional services using the
+                      Licensed Work.
+
+                      "Person" means any individual, corporation, limited
+                      liability company, partnership, association, nonprofit
+                      organization, governmental entity, or other legal or
+                      organizational entity.
+
+Change Date:          Four (4) years from the date the Licensed Work is first
+                      made available.
+
+Change License:       MIT License.
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact Blue Cypress, Inc.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License
+   can be included in a program with software provided under GPL Version 2.0
+   or a later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.

package/dist/ContractEntity.d.ts

@@ -0,0 +1,181 @@
+/**
+ * @fileoverview `ContractEntity` — the SHARED subclass. Browser and server both load it, so every
+ * rule here runs in both places: the user sees a refusal before the round trip, and the server
+ * enforces the same rule regardless of what the client did.
+ *
+ * IT DOES NOT OVERRIDE `Save()`. A shared class that persisted would have to work on a provider
+ * that cannot open a transaction. Persistence stays with `ContractEntityServer`; the browser ships
+ * the whole graph in one `MJ.SaveEntityGraph` call and the server runs the same executor
+ * (plan §6.3). Same split as orders' `OrderHeaderEntity`.
+ *
+ * WHAT IS DELIBERATELY NOT HERE:
+ *   · No `NewRecord()` status default. An earlier draft seeded `Status = 'Draft'`; D-19 removed the
+ *     column. A new contract reads as `Draft` because the layered base view derives it from the
+ *     absence of dates (ERD §4.5) — there is nothing to set, and nothing that can drift.
+ *   · No `DeclareRelatedRecords`. CodeGen emits `Modifications` onto the generated base class from
+ *     the `RelatedRecordCollection` metadata — edit that row, not this file.
+ *   · No provision/template consistency check. It needs a cross-entity read, so it is server-side
+ *     only (`ContractTemplateModificationEntityServer`); the picker prevents it in the UI.
+ *
+ * @module @mj-biz-apps/contracts-entities
+ */
+import { ValidationResult } from '@memberjunction/core';
+import { mjBizAppsContractsContractEntity } from './generated/entity_subclasses.js';
+/**
+ * Do two contracts sit at the SAME LEVEL of the tree — i.e. may one supersede the other?
+ *
+ * The pure half of the same-level supersession rule (ruled by Marcelo, 2026-08-20). A free function
+ * taking plain values for the same reason `FindDuplicateProvisionIDs` is one: the decision has three
+ * cases and two of them are easy to get backwards, and none of them needs a database to check.
+ *
+ *   · **both NULL → same level.** Two top-level agreements. This is the common case and the one a
+ *     naive `a === b` on nullable values gets right by accident and a SQL `=` gets WRONG — hence the
+ *     caller's `IS NULL` branch when it builds a filter.
+ *   · **one NULL, one set → DIFFERENT levels.** A change order claiming to replace a whole order form.
+ *     This is the case the rule exists to refuse.
+ *   · **both set → compare case-insensitively.** MJ returns UUIDs in either casing depending on how
+ *     the row was loaded, so a case-sensitive compare would call two siblings different levels and
+ *     refuse a legitimate re-papering.
+ *
+ * Note this is deliberately NOT "root only": two siblings under one parent are the same level, which
+ * is what lets a change order supersede another change order under the same agreement.
+ */
+export declare function IsSameContractLevel(myParentID: string | null | undefined, theirParentID: string | null | undefined): boolean;
+/**
+ * Which provision IDs appear more than once — the pure half of R-10's staged-rows rule.
+ *
+ * A free function taking plain values so the counting is testable without a provider or a
+ * `RelatedRecordCollection`, the same reason `ValidateValueLists` and `IsNewlySelected` are free
+ * functions. Every subtlety worth getting right is in here rather than in the caller:
+ *
+ *   · **case-insensitive** — MJ returns UUIDs in either casing depending on how the row was loaded, so
+ *     a case-sensitive compare would miss a duplicate while appearing to check for one;
+ *   · **blanks are skipped**, not grouped — several rows with no provision chosen yet are an
+ *     incomplete edit, not "the same provision twice", and reporting them as duplicates would refuse a
+ *     save the user is still composing;
+ *   · **each duplicated ID is reported once**, however many times it appears, so three copies of one
+ *     provision is one problem rather than two.
+ */
+export declare function FindDuplicateProvisionIDs(provisionIDs: readonly unknown[]): string[];
+export declare class ContractEntity extends mjBizAppsContractsContractEntity {
+    /**
+     * `HasModifications` is MONOTONIC: it must be true when modification rows exist, and it is never
+     * cleared automatically.
+     *
+     * WHY THE FLAG EXISTS AT ALL, given that the rows are right there to count. Because its job is to
+     * say "go read the PDF" *before* anyone has recorded the modifications. A derived flag would read
+     * false for every contract nobody has processed yet — which is exactly the population finance
+     * needs to be warned about. So a person asserts it, and this rule enforces the one direction that
+     * cannot be wrong: rows imply the flag.
+     *
+     * The other direction is deliberately unenforced. Clearing the flag after deleting every
+     * modification would be defensible, but it would also let a bulk delete quietly erase the warning
+     * on a contract whose paper really was negotiated. A human sets it false, or it stays true.
+     */
+    Validate(): ValidationResult;
+    /**
+     * R-10 — two modifications of the SAME provision, caught among the rows in hand.
+     *
+     * `UQ_ContractTemplateModification_Contract_Provision` is the floor, and it refuses this as a raw
+     * unique-index violation naming no field. This catches the case the browser can see for free: the
+     * collection is staged right here during a graph save, so a duplicate among those rows needs **no
+     * query at all**. The saved-rows half (a staged row colliding with one already in the table) needs
+     * a read and lives on the server subclass.
+     *
+     * WHY THIS IS ON `ContractEntity` AND NOT ON THE MODIFICATION. The item says "rule on the shared
+     * subclass" without saying which; only the CONTRACT holds the sibling rows. A modification cannot
+     * see its siblings, so the same rule written there could only ever be the one-query server version.
+     *
+     * Case-insensitive on the FK because MJ returns UUIDs in either casing, and a case-sensitive
+     * comparison would miss a duplicate while appearing to check for one.
+     */
+    private refuseDuplicateStagedModifications;
+    /**
+     * Drop generated NOT-NULL errors for fields the SAVE ITSELF fills in.
+     *
+     * `ContractNumber` is NOT NULL in metadata and is minted by `ContractEntityServer.Save()` from the
+     * sequence counter, under a lock. So on a record that has not been saved yet it is legitimately
+     * empty — and the generated check reported "Contract Number cannot be null", which the form
+     * surfaced as a refusal.
+     *
+     * That made the create path IMPOSSIBLE: every attempt to save a new contract through the UI was
+     * rejected for a field the user cannot fill and the server was about to. Measured in a browser, not
+     * reasoned about — the form refused with four errors and only three of them were real.
+     *
+     * After the first save the value exists, so an empty `ContractNumber` on a SAVED record is a
+     * genuine failure and is kept. That asymmetry is the whole rule, and it is why this cannot simply
+     * be "ignore ContractNumber".
+     *
+     * Same shape as orders' `IsSavePopulatedFieldError`, narrowed: contracts has exactly one
+     * save-populated field, because nothing here prepares child rows the way orders stamps line
+     * numbers and prices.
+     */
+    /**
+     * A hand-typed contract number may not look like a system-assigned one.
+     *
+     * WHY THIS REPLACED AN ERROR FILTER. This method sits where
+     * `dropSavePopulatedFieldErrors` used to: that one searched the validation result for
+     * `Source === 'ContractNumber'` and deleted it, so a new contract could be saved despite MJ
+     * correctly reporting a NOT NULL field as null. Deleting a real error because we believe
+     * something later will fix it is the same defect as blessing a self-reference because a
+     * generated validator "has it" — it converts an invalid state into a silent success the moment
+     * the belief stops holding. The cause is now removed instead: `V202608211000` gives the column a
+     * DEFAULT, which is how MJ models "NOT NULL but supplied on insert", so the error is never raised.
+     *
+     * WHAT THIS RULE IS. `Save()` honours a number the user typed, which is the right behaviour —
+     * migrated paper has its own references. But `CTR-<digits>` is the shape the sequence mints, so a
+     * hand-typed one can collide with a value the sequence has not reached yet. The collision would
+     * surface months later, on somebody else's save, as a unique-index violation with no explanation.
+     * So the namespaces are kept apart: type your own reference, or leave it blank.
+     *
+     * Note `\d+`, not `\d{6}`: `FORMAT(n,'D6')` pads to a MINIMUM of six digits and keeps growing
+     * past a million, so a seven-digit hand-typed number is just as collidable.
+     *
+     * ONLY ON AN UNSAVED RECORD, and only when the system did not assign it. An existing contract's
+     * stored number obviously matches the pattern and must not be retro-refused; and
+     * `ContractEntityServer.Save()` mints INTO this field before calling `super.Save()`, which
+     * validates — so without `NumberWasSystemAssigned` this rule would refuse the very numbers it is
+     * meant to protect.
+     */
+    private refuseReservedContractNumber;
+    /**
+     * Set by the server subclass when IT minted the number, so `refuseReservedContractNumber` can tell
+     * a system-assigned `CTR-…` from a hand-typed one. Protected rather than public: nothing outside
+     * the entity has any business claiming a number was system-assigned.
+     */
+    protected NumberWasSystemAssigned: boolean;
+    /**
+     * Whether modification rows are KNOWN to exist — as opposed to merely not known to be absent.
+     *
+     * The distinction is the whole subtlety of validating a collection in the browser. `Count > 0` is
+     * unambiguous: rows are staged or loaded, so they exist. `Count === 0` is ambiguous on a SAVED
+     * record whose collection was never loaded — empty there means *unknown*, and treating it as zero
+     * would let the flag be cleared on a contract whose modifications are sitting in the table.
+     *
+     * This method therefore only ever returns true on certainty. The unknown case is settled
+     * server-side, where a read is cheap and authoritative. Note `IsLoaded` alone is not the test:
+     * `Create()` does not mark a collection loaded, so a contract composed in the browser has
+     * modifications with `IsLoaded === false`. Orders' guard, same reasoning.
+     */
+    private modificationsKnownToExist;
+    /**
+     * Re-paper this contract: point it at the agreement that REPLACES it.
+     *
+     * ONE WRITE, NOT TWO. An earlier design also set `Status = 'Superseded'`; D-19 / R-18 removed the
+     * column precisely because the successor FK *is* the superseded state — the base view derives it
+     * (ERD §4.5), so there is no second fact that can disagree. The tautological
+     * `CK_Contract_SupersededHasSuccessor` constraint went with it.
+     *
+     * The successor is NOT saved here and neither is this record. The caller saves — normally as one
+     * graph — which keeps re-papering atomic: either both contracts reflect the supersession or
+     * neither does. Mirrors orders' `Confirm()`, which is likewise an intent-setter, not a persister.
+     */
+    Supersede(successor: ContractEntity): void;
+}
+/**
+ * Anti-tree-shake anchor. Importing this module is what fires `@RegisterClass`; a production build
+ * can drop an import whose class is never referenced, and a dropped registration means every rule
+ * above silently stops existing.
+ */
+export declare function LoadContractEntity(): void;
+//# sourceMappingURL=ContractEntity.d.ts.map

package/dist/ContractEntity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContractEntity.d.ts","sourceRoot":"","sources":["../src/ContractEntity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAwD,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE9G,OAAO,EAAE,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AAEjF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAM5H;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,EAAE,CAWpF;AAED,qBACa,cAAe,SAAQ,gCAAgC;IAChE;;;;;;;;;;;;;OAaG;IACa,QAAQ,IAAI,gBAAgB;IAuB5C;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,kCAAkC;IAkB1C;;;;;;;;;;;;;;;;;;;OAmBG;IACH;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,OAAO,CAAC,4BAA4B;IAmBpC;;;;OAIG;IACH,SAAS,CAAC,uBAAuB,UAAS;IAE1C;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,yBAAyB;IAIjC;;;;;;;;;;;OAWG;IACI,SAAS,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI;CAgBpD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/ContractEntity.js

@@ -0,0 +1,261 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+/**
+ * @fileoverview `ContractEntity` — the SHARED subclass. Browser and server both load it, so every
+ * rule here runs in both places: the user sees a refusal before the round trip, and the server
+ * enforces the same rule regardless of what the client did.
+ *
+ * IT DOES NOT OVERRIDE `Save()`. A shared class that persisted would have to work on a provider
+ * that cannot open a transaction. Persistence stays with `ContractEntityServer`; the browser ships
+ * the whole graph in one `MJ.SaveEntityGraph` call and the server runs the same executor
+ * (plan §6.3). Same split as orders' `OrderHeaderEntity`.
+ *
+ * WHAT IS DELIBERATELY NOT HERE:
+ *   · No `NewRecord()` status default. An earlier draft seeded `Status = 'Draft'`; D-19 removed the
+ *     column. A new contract reads as `Draft` because the layered base view derives it from the
+ *     absence of dates (ERD §4.5) — there is nothing to set, and nothing that can drift.
+ *   · No `DeclareRelatedRecords`. CodeGen emits `Modifications` onto the generated base class from
+ *     the `RelatedRecordCollection` metadata — edit that row, not this file.
+ *   · No provision/template consistency check. It needs a cross-entity read, so it is server-side
+ *     only (`ContractTemplateModificationEntityServer`); the picker prevents it in the UI.
+ *
+ * @module @mj-biz-apps/contracts-entities
+ */
+import { BaseEntity, ValidationErrorInfo, ValidationErrorType } from '@memberjunction/core';
+import { RegisterClass } from '@memberjunction/global';
+import { mjBizAppsContractsContractEntity } from './generated/entity_subclasses.js';
+/**
+ * Do two contracts sit at the SAME LEVEL of the tree — i.e. may one supersede the other?
+ *
+ * The pure half of the same-level supersession rule (ruled by Marcelo, 2026-08-20). A free function
+ * taking plain values for the same reason `FindDuplicateProvisionIDs` is one: the decision has three
+ * cases and two of them are easy to get backwards, and none of them needs a database to check.
+ *
+ *   · **both NULL → same level.** Two top-level agreements. This is the common case and the one a
+ *     naive `a === b` on nullable values gets right by accident and a SQL `=` gets WRONG — hence the
+ *     caller's `IS NULL` branch when it builds a filter.
+ *   · **one NULL, one set → DIFFERENT levels.** A change order claiming to replace a whole order form.
+ *     This is the case the rule exists to refuse.
+ *   · **both set → compare case-insensitively.** MJ returns UUIDs in either casing depending on how
+ *     the row was loaded, so a case-sensitive compare would call two siblings different levels and
+ *     refuse a legitimate re-papering.
+ *
+ * Note this is deliberately NOT "root only": two siblings under one parent are the same level, which
+ * is what lets a change order supersede another change order under the same agreement.
+ */
+export function IsSameContractLevel(myParentID, theirParentID) {
+    const a = myParentID ?? null;
+    const b = theirParentID ?? null;
+    if (a === null && b === null)
+        return true;
+    if (a === null || b === null)
+        return false;
+    return a.toLowerCase() === b.toLowerCase();
+}
+/**
+ * Which provision IDs appear more than once — the pure half of R-10's staged-rows rule.
+ *
+ * A free function taking plain values so the counting is testable without a provider or a
+ * `RelatedRecordCollection`, the same reason `ValidateValueLists` and `IsNewlySelected` are free
+ * functions. Every subtlety worth getting right is in here rather than in the caller:
+ *
+ *   · **case-insensitive** — MJ returns UUIDs in either casing depending on how the row was loaded, so
+ *     a case-sensitive compare would miss a duplicate while appearing to check for one;
+ *   · **blanks are skipped**, not grouped — several rows with no provision chosen yet are an
+ *     incomplete edit, not "the same provision twice", and reporting them as duplicates would refuse a
+ *     save the user is still composing;
+ *   · **each duplicated ID is reported once**, however many times it appears, so three copies of one
+ *     provision is one problem rather than two.
+ */
+export function FindDuplicateProvisionIDs(provisionIDs) {
+    const counts = new Map();
+    const duplicates = [];
+    for (const raw of provisionIDs) {
+        const id = String(raw ?? '').trim().toLowerCase();
+        if (!id)
+            continue;
+        const next = (counts.get(id) ?? 0) + 1;
+        counts.set(id, next);
+        if (next === 2)
+            duplicates.push(id);
+    }
+    return duplicates;
+}
+let ContractEntity = class ContractEntity extends mjBizAppsContractsContractEntity {
+    constructor() {
+        super(...arguments);
+        /**
+         * Set by the server subclass when IT minted the number, so `refuseReservedContractNumber` can tell
+         * a system-assigned `CTR-…` from a hand-typed one. Protected rather than public: nothing outside
+         * the entity has any business claiming a number was system-assigned.
+         */
+        this.NumberWasSystemAssigned = false;
+    }
+    /**
+     * `HasModifications` is MONOTONIC: it must be true when modification rows exist, and it is never
+     * cleared automatically.
+     *
+     * WHY THE FLAG EXISTS AT ALL, given that the rows are right there to count. Because its job is to
+     * say "go read the PDF" *before* anyone has recorded the modifications. A derived flag would read
+     * false for every contract nobody has processed yet — which is exactly the population finance
+     * needs to be warned about. So a person asserts it, and this rule enforces the one direction that
+     * cannot be wrong: rows imply the flag.
+     *
+     * The other direction is deliberately unenforced. Clearing the flag after deleting every
+     * modification would be defensible, but it would also let a bulk delete quietly erase the warning
+     * on a contract whose paper really was negotiated. A human sets it false, or it stays true.
+     */
+    Validate() {
+        const result = super.Validate();
+        this.refuseReservedContractNumber(result);
+        if (this.HasModifications === false && this.modificationsKnownToExist()) {
+            result.Success = false;
+            result.Errors.push(new ValidationErrorInfo('HasModifications', `Contract ${this.ContractNumber ?? ''} records ${this.Modifications.Count} modification(s) to the ` +
+                `standard agreement, so it cannot be marked as unmodified. Remove the modifications first if ` +
+                `the agreement really is standard.`, this.HasModifications, ValidationErrorType.Failure));
+        }
+        this.refuseDuplicateStagedModifications(result);
+        return result;
+    }
+    /**
+     * R-10 — two modifications of the SAME provision, caught among the rows in hand.
+     *
+     * `UQ_ContractTemplateModification_Contract_Provision` is the floor, and it refuses this as a raw
+     * unique-index violation naming no field. This catches the case the browser can see for free: the
+     * collection is staged right here during a graph save, so a duplicate among those rows needs **no
+     * query at all**. The saved-rows half (a staged row colliding with one already in the table) needs
+     * a read and lives on the server subclass.
+     *
+     * WHY THIS IS ON `ContractEntity` AND NOT ON THE MODIFICATION. The item says "rule on the shared
+     * subclass" without saying which; only the CONTRACT holds the sibling rows. A modification cannot
+     * see its siblings, so the same rule written there could only ever be the one-query server version.
+     *
+     * Case-insensitive on the FK because MJ returns UUIDs in either casing, and a case-sensitive
+     * comparison would miss a duplicate while appearing to check for one.
+     */
+    refuseDuplicateStagedModifications(result) {
+        const provisionIDs = this.Modifications.Items.map((mod) => mod.Get('ContractTemplateProvisionID'));
+        const duplicates = FindDuplicateProvisionIDs(provisionIDs);
+        if (duplicates.length === 0)
+            return;
+        result.Success = false;
+        result.Errors.push(new ValidationErrorInfo('Modifications', `${duplicates.length === 1 ? 'A provision is' : `${duplicates.length} provisions are`} modified more ` +
+            `than once on this contract. A contract records ONE negotiated wording per standard clause — ` +
+            `combine the duplicates into a single modification.`, duplicates.length, ValidationErrorType.Failure));
+    }
+    /**
+     * Drop generated NOT-NULL errors for fields the SAVE ITSELF fills in.
+     *
+     * `ContractNumber` is NOT NULL in metadata and is minted by `ContractEntityServer.Save()` from the
+     * sequence counter, under a lock. So on a record that has not been saved yet it is legitimately
+     * empty — and the generated check reported "Contract Number cannot be null", which the form
+     * surfaced as a refusal.
+     *
+     * That made the create path IMPOSSIBLE: every attempt to save a new contract through the UI was
+     * rejected for a field the user cannot fill and the server was about to. Measured in a browser, not
+     * reasoned about — the form refused with four errors and only three of them were real.
+     *
+     * After the first save the value exists, so an empty `ContractNumber` on a SAVED record is a
+     * genuine failure and is kept. That asymmetry is the whole rule, and it is why this cannot simply
+     * be "ignore ContractNumber".
+     *
+     * Same shape as orders' `IsSavePopulatedFieldError`, narrowed: contracts has exactly one
+     * save-populated field, because nothing here prepares child rows the way orders stamps line
+     * numbers and prices.
+     */
+    /**
+     * A hand-typed contract number may not look like a system-assigned one.
+     *
+     * WHY THIS REPLACED AN ERROR FILTER. This method sits where
+     * `dropSavePopulatedFieldErrors` used to: that one searched the validation result for
+     * `Source === 'ContractNumber'` and deleted it, so a new contract could be saved despite MJ
+     * correctly reporting a NOT NULL field as null. Deleting a real error because we believe
+     * something later will fix it is the same defect as blessing a self-reference because a
+     * generated validator "has it" — it converts an invalid state into a silent success the moment
+     * the belief stops holding. The cause is now removed instead: `V202608211000` gives the column a
+     * DEFAULT, which is how MJ models "NOT NULL but supplied on insert", so the error is never raised.
+     *
+     * WHAT THIS RULE IS. `Save()` honours a number the user typed, which is the right behaviour —
+     * migrated paper has its own references. But `CTR-<digits>` is the shape the sequence mints, so a
+     * hand-typed one can collide with a value the sequence has not reached yet. The collision would
+     * surface months later, on somebody else's save, as a unique-index violation with no explanation.
+     * So the namespaces are kept apart: type your own reference, or leave it blank.
+     *
+     * Note `\d+`, not `\d{6}`: `FORMAT(n,'D6')` pads to a MINIMUM of six digits and keeps growing
+     * past a million, so a seven-digit hand-typed number is just as collidable.
+     *
+     * ONLY ON AN UNSAVED RECORD, and only when the system did not assign it. An existing contract's
+     * stored number obviously matches the pattern and must not be retro-refused; and
+     * `ContractEntityServer.Save()` mints INTO this field before calling `super.Save()`, which
+     * validates — so without `NumberWasSystemAssigned` this rule would refuse the very numbers it is
+     * meant to protect.
+     */
+    refuseReservedContractNumber(result) {
+        if (this.IsSaved || this.NumberWasSystemAssigned)
+            return;
+        const typed = (this.ContractNumber ?? '').trim();
+        if (!typed || !/^CTR-\d+$/i.test(typed))
+            return;
+        result.Success = false;
+        result.Errors.push(new ValidationErrorInfo('ContractNumber', `The CTR-#### pattern is reserved for contract numbers the system assigns, so "${typed}" cannot be ` +
+            `entered by hand — a number the sequence has not reached yet would collide with it later, on ` +
+            `somebody else's save. Leave this blank to have one assigned, or enter your own reference in a ` +
+            `different format.`, this.ContractNumber, ValidationErrorType.Failure));
+    }
+    /**
+     * Whether modification rows are KNOWN to exist — as opposed to merely not known to be absent.
+     *
+     * The distinction is the whole subtlety of validating a collection in the browser. `Count > 0` is
+     * unambiguous: rows are staged or loaded, so they exist. `Count === 0` is ambiguous on a SAVED
+     * record whose collection was never loaded — empty there means *unknown*, and treating it as zero
+     * would let the flag be cleared on a contract whose modifications are sitting in the table.
+     *
+     * This method therefore only ever returns true on certainty. The unknown case is settled
+     * server-side, where a read is cheap and authoritative. Note `IsLoaded` alone is not the test:
+     * `Create()` does not mark a collection loaded, so a contract composed in the browser has
+     * modifications with `IsLoaded === false`. Orders' guard, same reasoning.
+     */
+    modificationsKnownToExist() {
+        return this.Modifications.Count > 0;
+    }
+    /**
+     * Re-paper this contract: point it at the agreement that REPLACES it.
+     *
+     * ONE WRITE, NOT TWO. An earlier design also set `Status = 'Superseded'`; D-19 / R-18 removed the
+     * column precisely because the successor FK *is* the superseded state — the base view derives it
+     * (ERD §4.5), so there is no second fact that can disagree. The tautological
+     * `CK_Contract_SupersededHasSuccessor` constraint went with it.
+     *
+     * The successor is NOT saved here and neither is this record. The caller saves — normally as one
+     * graph — which keeps re-papering atomic: either both contracts reflect the supersession or
+     * neither does. Mirrors orders' `Confirm()`, which is likewise an intent-setter, not a persister.
+     */
+    Supersede(successor) {
+        if (!successor?.ID) {
+            throw new Error(`Cannot supersede contract ${this.ContractNumber ?? this.ID}: the replacement contract must be ` +
+                `saved first, so that its ID exists to point at.`);
+        }
+        if (successor.ID === this.ID) {
+            throw new Error(`Contract ${this.ContractNumber ?? this.ID} cannot supersede itself. ` +
+                `(CK_Contract_SupersededNotSelf would refuse the save regardless.)`);
+        }
+        this.SupersededByContractID = successor.ID;
+    }
+};
+ContractEntity = __decorate([
+    RegisterClass(BaseEntity, 'MJ_BizApps_Contracts: Contracts')
+], ContractEntity);
+export { ContractEntity };
+/**
+ * Anti-tree-shake anchor. Importing this module is what fires `@RegisterClass`; a production build
+ * can drop an import whose class is never referenced, and a dropped registration means every rule
+ * above silently stops existing.
+ */
+export function LoadContractEntity() {
+    void ContractEntity;
+}
+//# sourceMappingURL=ContractEntity.js.map

package/dist/ContractEntity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContractEntity.js","sourceRoot":"","sources":["../src/ContractEntity.ts"],"names":[],"mappings":"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"}