@mj-biz-apps/contracts-core-entities-server 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/ContractEntityServer.d.ts

@@ -0,0 +1,352 @@
+/**
+ * @fileoverview `ContractEntityServer` — the rules that CANNOT run in a browser.
+ *
+ * Registered later than the shared `ContractEntity`, so MJ's ClassFactory resolves this one on the
+ * server while the browser keeps the shared class (plan §6.3). Everything a client should be able to
+ * preflight lives on the shared class instead; what is here needs a lock or a cross-entity read.
+ *
+ * @module @mj-biz-apps/contracts-core-entities-server
+ */
+import { BaseEntity, type EntityDeleteOptions, ValidationResult } from '@memberjunction/core';
+import { ContractEntity } from '@mj-biz-apps/contracts-entities';
+/**
+ * Whether a foreign key is being CHOSEN right now, as opposed to merely being present.
+ *
+ * A free function so it can be unit-tested against a duck-typed record without a provider — the same
+ * reason `ValidateValueLists` and `ExplainMissingRequiredFields` are free functions. The semantics
+ * are the whole point and they are easy to get subtly wrong, so they are pinned by tests rather than
+ * by this comment:
+ *
+ *   · NEW record          -> any value is a new selection.  (accounting's identity lock skips this
+ *                            case, correctly for its purpose and wrongly for ours)
+ *   · SAVED, key changed  -> a new selection.
+ *   · SAVED, key the same -> NOT a new selection, whatever the referenced row now says.
+ *
+ * The comparison is case-insensitive and string-wise because these are UUIDs, which MJ can hand back
+ * in either casing depending on how the record was loaded (MJ's UUID_COMPARISON_GUIDE). A `!==` here
+ * would report a change on a record nobody touched.
+ */
+export declare function IsNewlySelected(entity: BaseEntity, fieldName: string): boolean;
+export declare class ContractEntityServer extends ContractEntity {
+    /**
+     * Mint `ContractNumber` on first save, then persist.
+     *
+     * WHY THE NUMBER IS MINTED HERE and not defaulted in SQL. It comes from a singleton counter that
+     * has to be taken under a lock inside the save's own transaction, so a rollback releases the
+     * number instead of burning it. A column default cannot do that, and a client cannot be trusted
+     * with it.
+     *
+     * Contracts needs no `SkipRelatedCollections` dance, unlike orders: nothing here prepares child
+     * rows before the graph executor runs, so the plain save carries `Modifications` with it.
+     */
+    Save(): Promise<boolean>;
+    /**
+     * Server-authoritative rules that need to read another entity.
+     *
+     * SETTLE THE `HasModifications` UNKNOWN CASE. The shared `ContractEntity.Validate()` only rejects
+     * a false flag when it can PROVE rows exist — `Modifications.Count > 0`. On an ordinary form load
+     * the collection is not loaded, so `Count === 0` means *unknown*, and the shared guard stays
+     * silent by design rather than refusing a legitimate save.
+     *
+     * That design is only honest if something settles the unknown case, and until now nothing did:
+     * load a saved contract without its modifications, set `HasModifications = false`, save, and it
+     * succeeded — flag false with rows in the table, which ERD §4.4 explicitly rejects and which the
+     * modification subclass's own comment calls the single most misleading state this app can produce.
+     * The shared class's comment PROMISED this check existed. Caught on review of PR #9.
+     *
+     * One `EXISTS`, and only when it can matter (`IsSaved && HasModifications === false`), so the
+     * ordinary save pays nothing. The message is the shared class's, deliberately — the user should
+     * not be able to tell which tier refused them.
+     *
+     * THE TYPE DECIDES WHERE IN THE TREE A CONTRACT MAY SIT, and whether it needs its own paper.
+     * `ContractType.MustBeRoot` / `MustBeChild` / `TemplateRequired` — three booleans, all read from the
+     * one memoised type row. The rules need that row, which is a join the browser has no business
+     * doing, so the shared class cannot carry them (ERD §7.1).
+     *
+     * ⚠ TWO GENERATIONS OF DEFECT ARE BURIED HERE, and both are worth remembering.
+     *
+     * FIRST, this compared the type's NAME to the string 'Change Order'. A display name is not a rule:
+     * renaming that lookup row — an ordinary thing to do — silently stopped the check from ever firing,
+     * with nothing failing and no error to notice (fixed 2026-08-19).
+     *
+     * SECOND, the column that replaced the name match was a THREE-STATE STRING,
+     * `ParentStatusRequirement IN ('Required','Prohibited')` or NULL. Ruled out by Marcelo on
+     * 2026-08-20 as confusing and overly complex, with the transposition argument as the proof: a
+     * column whose values INVERT the rule when read in the wrong order is a column that will
+     * eventually be read in the wrong order. Now two booleans, mutually exclusive by
+     * `CK_ContractType_RootOrChild`, and "both false" means unrestricted — a real and in fact majority
+     * state (V202608200300).
+     *
+     * Both placement directions are enforced, because a rule that only ever checks one of them is half
+     * decoration: `MustBeChild` refuses a missing parent (a change order that amends nothing would
+     * never appear in the original agreement's lineage), and `MustBeRoot` refuses a present one (a root
+     * agreement sitting under another contract is a lineage ring waiting to happen — see R-3).
+     */
+    ValidateAsync(): Promise<ValidationResult>;
+    /**
+     * R-8 — a contract that other records point at cannot be deleted, and the refusal says who.
+     *
+     * THREE DEPENDENCIES, and the two lineage ones are the reason this is not obvious. A contract is
+     * referenced not only by its modifications but by any contract naming it as `ParentContractID`
+     * (its change orders) or as `SupersededByContractID` (the agreement it replaced). Both of those are
+     * self-references on `Contract`, so the rows blocking the delete are *other contracts* — and the
+     * user is looking at the record they wanted gone, not at the ones pointing to it. Naming them is
+     * the whole value.
+     *
+     * Deleting a superseded contract is the case worth spelling out: it is the *predecessor* in a
+     * re-papering chain, so removing it destroys the history the successor exists to continue.
+     */
+    Delete(options?: EntityDeleteOptions): Promise<boolean>;
+    /**
+     * R-5 — A RETIRED TYPE MUST NOT BE *NEWLY* SELECTED, and the word doing the work is "newly".
+     *
+     * A contract that already references a type keeps working. We assume the type was Active when it
+     * was chosen, and retiring a type is not a statement about the contracts already signed under it —
+     * refusing to save an existing contract because a lookup row was retired years later would make
+     * the retirement itself a destructive act. So this is a rule about the EDIT, not about the row.
+     *
+     * "Newly selected" means one of exactly two things, and both must be covered:
+     *   · the record is NEW and names the type at all, or
+     *   · the record is SAVED and the foreign key CHANGED.
+     *
+     * That first clause is why this does not reuse `GLAccountEntityServer`'s shape verbatim.
+     * Accounting's identity lock returns early when `OldValue` is null — correct there, because it is
+     * asking "did an existing value change". Here the same early return would skip every CREATE, which
+     * is the primary case the rule exists for: the Configuration page promises a retired type "stops
+     * being offered for new contracts", and a create is the newest selection there is.
+     *
+     * TIER: code only, no trigger. `Status` lives on another table so a CHECK cannot see it, and the
+     * plan ruled a trigger not worth it — the failure mode is a person picking a retired value in our
+     * own UI, not silent corruption by an outside writer.
+     *
+     * COST: the `ContractTypeID` half is FREE — `typeRule()` already reads that row for the
+     * parent-status rule, and `Status` now rides along on the same RunView. The `ContractTemplateID`
+     * half costs two reads (template -> its type -> that type's `Status`) and only runs when the
+     * template FK is newly selected, which is rare. There is no single view exposing the template's
+     * type's status; `vwContractTemplates` carries the type's NAME, not its `Status`.
+     */
+    private refuseRetiredSelections;
+    /**
+     * Whether this foreign key is being chosen right now, as opposed to merely being present.
+     *
+     * On a NEW record any value is a new selection. On a SAVED one, only a change counts — and the
+     * comparison is case-insensitively string-wise because these are UUIDs, which MJ can hand back in
+     * either casing depending on the path that loaded them (see MJ's UUID_COMPARISON_GUIDE). Comparing
+     * them with `!==` would report a change on a record nobody touched, which would refuse saves of
+     * contracts whose type is perfectly legal.
+     */
+    private isNewlySelected;
+    /**
+     * The NAME of the template's type when that type is retired, or null.
+     *
+     * Two hops, because `Status` lives on `ContractTemplateType` and the contract points at a
+     * `ContractTemplate`. Returns the type's name rather than a boolean so the refusal can say WHICH
+     * kind of template was retired — "that template is an Order Form, which we no longer issue" is
+     * actionable where "invalid template" sends the user back to the same picker.
+     */
+    private retiredTemplateType;
+    /**
+     * R-3 — a contract may not end up in its own lineage, on either axis.
+     *
+     * THE HOLE. `CK_Contract_ParentNotSelf` and `CK_Contract_SupersededNotSelf` stop only `A -> A`.
+     * Nothing stopped `A -> B -> A`, or a longer ring, because every individual save is legal in
+     * isolation: setting B's parent to A is fine, and later setting A's parent to B is fine — the row
+     * being written references a different row, which is all a CHECK can see.
+     *
+     * A cycle can only be created by THE EDGE BEING ADDED, which is what makes the check cheap: the
+     * question is not "is the graph acyclic" but "starting from the parent I am proposing, can I reach
+     * myself?" One upward walk along an indexed FK, one row per level, and change-order chains are 1–3
+     * deep in practice. `Depth < 50` caps it and — more importantly — means an ALREADY-corrupt ring
+     * terminates instead of spinning.
+     *
+     * ⚠ THE CONSEQUENCE OF A CYCLE IS WORSE THAN THE PLAN SAYS, and this is worth recording because it
+     * changes the tier. R-3 argued a cycle "corrupts nothing silently — it makes the Lineage panel walk
+     * forever, which is loud." That was true when written. It is not true now: `vwContracts` computes
+     * `RootParentContractID` and `RootSupersededByContractID` through
+     * `fnContract*_GetRootID`, whose CTE walks to `Depth < 100` and then selects the row
+     * `WHERE ParentContractID IS NULL`. In a ring **no row satisfies that**, so the function returns no
+     * row and the column comes back **NULL** — silently wrong, on the app's primary view, for every
+     * contract in the ring, while also costing 100 levels of recursion per row on every read. So a
+     * cycle is quiet after all, which is exactly the shape of defect this app keeps designing away.
+     *
+     * SKIPPED ON A CREATE. An unsaved contract has an ID but no row, so nothing can point at it and no
+     * walk can reach it. Skipped when the proposed target IS this record, too — that is `A -> A`, which
+     * the generated CHECK validator already reports, and two errors for one mistake is its own defect.
+     */
+    private refuseLineageCycles;
+    /**
+     * A contract may not be its own parent, nor its own successor. Reported HERE, unconditionally.
+     *
+     * WHY THIS EXISTS when `CK_Contract_ParentNotSelf` / `CK_Contract_SupersededNotSelf` and their
+     * generated validators all cover it: because the generated validators DO NOT actually cover it.
+     * They are LLM-authored from the constraint text (`generateValidatorFunctionFromCheckConstraint`
+     * → the `CodeGen: Check Constraint Parser` prompt), and both emitted `===` on a `uniqueidentifier`:
+     *
+     *     if (this.SupersededByContractID != null && this.SupersededByContractID === this.ID) { ... }
+     *
+     * MJ returns UUIDs in either casing depending on how a row was loaded, so a lowercase value against
+     * an uppercase `ID` is the SAME contract and that check silently misses it. Filed in MJ-UPSTREAM.md.
+     *
+     * AND THE RULE IS CHECKED WHOLE, not only the part the generated code misses. Covering just the
+     * casing-differs case and deferring the rest would bless a genuinely invalid state on an assumption
+     * about code this class does not own — and the moment that code changes, an invalid state starts
+     * reading as success. The cost of overlap is one duplicated message; the cost of the gap is a wrong
+     * save. This is also why the two lineage guards below delegate here rather than each deciding: one
+     * owner, checked fully, in this file, where the skip can be verified by reading it.
+     */
+    private refuseSelfReferences;
+    /**
+     * A contract may only supersede a contract at the SAME LEVEL of the tree — same `ParentContractID`.
+     *
+     * WHY THIS IS NOT "ROOT ONLY" (ruled by Marcelo, 2026-08-20). The obvious-looking rule is that only
+     * a top-level agreement may be re-papered. It is wrong in both directions. A change order genuinely
+     * does get renegotiated and replaced by a second change order under the same order form — forbidding
+     * that would force somebody to DELETE the first one, destroying the history re-papering exists to
+     * preserve. And "root only" would still permit the incoherent case: a change order claiming to
+     * replace a whole order form, which asserts that a subordinate document replaced the agreement it
+     * hangs off.
+     *
+     * So the axis that matters is not depth, it is SIBLINGHOOD. `ParentContractID` says what a document
+     * sits under; `SupersededByContractID` says what replaced it. A supersession that crosses levels is
+     * the only genuinely meaningless combination, and same-parent is exactly the predicate that excludes
+     * it while allowing everything real: two roots (both NULL) or two siblings (same parent).
+     *
+     * TYPE IS DELIBERATELY NOT CONSTRAINED. An Order Form replaced by an Order Form is the common case,
+     * but a Payment Link customer graduating to signed paper is a real cross-type supersession — and
+     * `Payment Link -> Order Form` is precisely the upgrade path the two types exist to distinguish.
+     * Constraining `ContractTypeID` here would forbid it for no benefit.
+     *
+     * WHY THIS IS NOT A CHECK CONSTRAINT. The rule compares THIS row's `ParentContractID` with ANOTHER
+     * row's, and a CHECK sees only the row being written — the same reason `refuseLineageCycles` lives
+     * here. One indexed read of the target contract is the whole cost.
+     *
+     * RUNS ON CREATE TOO, unlike `refuseLineageCycles`. A cycle is impossible before the row exists
+     * (nothing can point at it yet), but a cross-level supersession is entirely possible on a brand-new
+     * contract — a successor composed in the browser names its predecessor before either is saved, which
+     * is the primary flow this rule exists to police. Gated on `isNewlySelected` instead, so an ordinary
+     * re-save of an existing chain is not re-policed and legacy rows are not retro-refused.
+     */
+    private refuseCrossLevelSupersession;
+    /**
+     * Walk up `<column>` from `startID`; return the chain as text if it reaches this record, else null.
+     *
+     * Returns the CHAIN rather than a boolean so the refusal can show the ring — "A -> B -> A" is
+     * something a person can act on, where "cycle detected" sends them to guess which edge to remove.
+     *
+     * The column name comes from a fixed internal list, never from input, and both IDs are checked
+     * against a UUID shape before interpolation — `ExecuteSQL`'s object-parameter form needs the
+     * concrete `SQLServerDataProvider` type rather than the `DatabaseProviderBase` this class holds
+     * (see the note on `assignContractNumber`), so a guard plus interpolation is the honest option here
+     * rather than a cast that switches off checking.
+     */
+    private lineageReachesSelf;
+    /**
+     * A shrotcut to get the datbaseProvider.
+     *
+     * `ExecuteSQL<T>(query, parameters?, options?, contextUser?)` is a public member of
+     * `DatabaseProviderBase`, which `@memberjunction/core` exports — so the four
+     * `as unknown as { ExecuteSQL: … }` casts this replaces were never necessary. Each of them
+     * re-declared a narrower signature than the real one: no generic (forcing a second cast on every
+     * result), and no `contextUser` parameter, which made the API look as though it could not carry a
+     * context user at all. Worse, `as unknown as` switches off checking, so a signature change
+     * upstream would have compiled here and failed at runtime.
+     *
+     * `ProviderToUse` is typed as the metadata-provider interface, which does not declare
+     * `ExecuteSQL`; this is a narrowing cast to the concrete base class, which is what a server-side
+     * entity subclass always has. It is one cast in one place instead of four scattered ones, and it
+     * keeps the real generic signature.
+     */
+    private get db();
+    /**
+     * Whether any modification row exists for this contract, read from the DATABASE rather than the
+     * collection — which is the whole point: the collection is exactly what the browser could not
+     * know about. `TOP 1` because existence is the question, not the count.
+     */
+    private modificationRowsExist;
+    /**
+     * What this contract's TYPE says about naming a parent: `'Required'`, `'Prohibited'` or null.
+     *
+     * One scalar read, no entity load, and memoised for the call — `ValidateAsync` asks for the
+     * requirement and then for the type's name to build the message, and a validation pass should not
+     * make two round trips to say one thing.
+     */
+    private typeRule;
+    /**
+     * Cleared on nothing, and that is safe: a contract's type can change between saves, but this cache
+     * lives only for the duration of one `ValidateAsync` call tree — the field is re-read from the
+     * database on the next validation because a new entity instance is what a new save uses.
+     */
+    private cachedTypeRule;
+    /**
+     * R-12 — a contract may not reference a template nobody can read.
+     *
+     * `IsUsable` is derived in `vwContractTemplates`: 1 when the template records a `SourceURL` **or**
+     * has a file attached, 0 when it has neither. The flag and this refusal do different jobs and both
+     * are needed (ruled 2026-08-20):
+     *
+     *   · **the flag is the affordance** — someone authoring a template sees the red "Unusable" chip and
+     *     fixes it, rather than being blocked by a condition they cannot see;
+     *   · **this refusal is the floor** — a contract citing standard terms nobody can read is the actual
+     *     harm, and it is worth stopping at the moment it would happen.
+     *
+     * Shipping only the flag leaves the harm unprevented; shipping only the refusal is the confusing
+     * version this item started as, where a person is refused for something invisible.
+     *
+     * ONLY ON A NEW REFERENCE. Whether an EXISTING contract should be affected when its template later
+     * becomes unusable is a lifecycle question, and it is R-15's — not this one. So this fires on the
+     * same `isNewlySelected` gate as R-5, which also means an ordinary re-save of an existing contract
+     * costs nothing.
+     */
+    private refuseUnusableTemplate;
+    /**
+     * R-4 (certain half) — do not clear `ContractTemplateID` while modifications on THIS contract point
+     * at provisions of THAT template.
+     *
+     * Clearing it would leave every one of those modifications comparing negotiated language against
+     * standard language the contract no longer claims to incorporate — the modification rows survive
+     * and quietly stop meaning anything, which is the app's worst failure shape.
+     *
+     * ⚠ THIS IS THE NARROW HALF ON PURPOSE. The full rule is *"reject clearing when a modification
+     * ANYWHERE IN THE TREE references that template and it is not reachable elsewhere in the tree"*,
+     * which the plan DEFERS to ride with R-14 — not on cost (it is the same walk, and chains are 1–3
+     * deep) but on sequencing, so the ancestor walk is written once against a settled tree model. This
+     * half covers modifications on this contract only. A modification on a CHILD contract pointing at
+     * the template this contract is clearing is **not yet caught here**; the modification-side rule
+     * below refuses to SAVE such a row, so the gap is the pre-existing row, not a new one.
+     */
+    private refuseClearingAReferencedTemplate;
+    /** How many of THIS contract's modifications cite a provision of the given template. */
+    private modificationsAgainstTemplate;
+    /**
+     * Mint the next contract number by calling the database's own numbering procedure.
+     *
+     * WHY A SPROC AND NOT `RunView` / `RunQuery` / `BaseEntity`. This is an atomic
+     * read-modify-write, and none of those can express one: `RunView` is read-only, `RunQuery` is a
+     * read surface (hiding DML inside a "query" would be worse than being honest about it), and the
+     * entity path removes the lock — two concurrent creates would both read N, both mint the same
+     * number, and the collision would surface later as a unique-index violation on the insert rather
+     * than as a serialised wait.
+     *
+     * So the lock stays in the database, in a DATABASE OBJECT rather than a TypeScript string.
+     * `spAssignNextContractNumber` (V202608192200) holds the `HOLDLOCK, UPDLOCK` and the format; this
+     * method is one dialect-free `EXEC`. That is accounting's pattern, adopted rather than invented —
+     * `SequenceService.ts` there keeps `spAssignNextJournalEntryNumber` at DB level for the same
+     * stated reason. Orders still inlines the same UPDATE in four places, which is what this stops
+     * doing.
+     *
+     * It also makes the PostgreSQL port a database exercise: write a PG function with this name and
+     * signature and no application code changes.
+     *
+     * `isMutation: true` matters and was missing while this was inline: MJ's SQL-statement logging
+     * uses it to know a statement CHANGED data, which is what lets a logging session capture the
+     * mutation. `description` names the operation in that log.
+     *
+     * ⚠ NOT gap-free. On a standalone save the number is consumed before the row's own transaction
+     * opens, so a later failure has already spent it; inside a graph save a rollback releases it. The
+     * unique index is the real guard.
+     */
+    private assignContractNumber;
+}
+/** Anti-tree-shake anchor — see the note in index.ts. */
+export declare function LoadContractEntityServer(): void;
+//# sourceMappingURL=ContractEntityServer.d.ts.map

package/dist/ContractEntityServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContractEntityServer.d.ts","sourceRoot":"","sources":["../src/ContractEntityServer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EACH,UAAU,EAEV,KAAK,mBAAmB,EAIxB,gBAAgB,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,cAAc,EAAuB,MAAM,iCAAiC,CAAC;AAGtF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAK9E;AAqBD,qBACa,oBAAqB,SAAQ,cAAc;IACpD;;;;;;;;;;OAUG;IACmB,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IA0B9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACmB,aAAa,IAAI,OAAO,CAAC,gBAAgB,CAAC;IA+EhE;;;;;;;;;;;;OAYG;IACmB,MAAM,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAiC7E;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;YACW,uBAAuB;IAmCrC;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAIvB;;;;;;;OAOG;YACW,mBAAmB;IA6BjC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;YACW,mBAAmB;IA4CjC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,oBAAoB;IAY5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;YACW,4BAA4B;IA6D1C;;;;;;;;;;;OAWG;YACW,kBAAkB;IA0BhC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,KAAK,EAAE,GAEb;IAED;;;;OAIG;YACW,qBAAqB;IAkBnC;;;;;;OAMG;YACW,QAAQ;IAkBtB;;;;OAIG;IACH,OAAO,CAAC,cAAc,CAAkD;IAGxE;;;;;;;;;;;;;;;;;;;OAmBG;YACW,sBAAsB;IAuDpC;;;;;;;;;;;;;;;OAeG;YACW,iCAAiC;IA0B/C,wFAAwF;YAC1E,4BAA4B;IAgB1C;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;YACW,oBAAoB;CAyBrC;AAED,yDAAyD;AACzD,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}