@mj-biz-apps/sales-core-entities-server 5.1.0

package/dist/DealEntityServer.d.ts

@@ -0,0 +1,625 @@
+/**
+ * @fileoverview `DealEntityServer` — the rules that need a database, on the one path every write takes.
+ *
+ * WHAT CHANGED, AND WHY THIS FILE GOT MUCH SMALLER. A deal is not one row, and until MJ v6 this class
+ * had to compose the tree itself: transient `Lines` / `PaymentSchedule` arrays, a deletion queue, a
+ * re-sequencer, and a `Save()` override that walked header → deletions → children inside an explicit
+ * `BeginTransaction` / `CommitTransaction`. All of that is now **Related Record Collections** —
+ * declared in metadata, generated onto `mjBizAppsSalesDealEntity`, and executed by MJ's
+ * `EntitySavePlan` inside one `EntityTransactionScope`. The framework does header-before-children and
+ * deletions-before-inserts because those orderings are inherent to the problem, not to this app.
+ *
+ * Deleting a hand-rolled implementation in favour of the framework's is only worth it when the
+ * framework's is at least as careful. It is: `RelatedRecordCollection.Load()` throws on a failed read
+ * AND refuses to load over unsaved children, which is the same "a failed load and an empty collection
+ * must never look alike" contract the hand-written `LoadLines` documented — plus a guard against a
+ * stray reload discarding work mid-edit, which the hand-written one did not have.
+ *
+ * WHAT REMAINS HERE IS EXACTLY WHAT NEEDS A DATABASE:
+ *   - `DealNumber` — a gap-free counter taken from a locked row, inside the save's transaction.
+ *   - The OWNER STAMP — `Deal.OwnerEmployeeID` derived from the `DealTeamMember` carrying the owner
+ *     role, resolved from `DealRole.IsOwnerRole` rather than from any role name.
+ *
+ * WHAT THIS FILE MUST NEVER DO. Arithmetic on money. No summing lines into `Amount`, no applying
+ * `RequestedDiscountPct`, no checking that the payment schedule adds up. `Amount` is a cached answer
+ * from `Orders.PreviewOrder` carrying its own provenance; the signed figures on a line are
+ * transcriptions.
+ *
+ * The form-shaped rules are NOT here — they are on {@link DealEntity} in `sales-entities`, which this
+ * class extends, so they run in the browser as well as on the server. Extending `DealEntity` rather
+ * than the generated entity is load-bearing: extend the generated one and every rule in that file
+ * silently stops applying on the server.
+ *
+ *   - The CLOSE LOCK (S4). Once the deal's status carries `DealStatusType.LocksDeal = 1`, the header
+ *     (except Description / NextStep), its lines, its instalments and its team are immutable, and
+ *     reopening goes through `Sales.ReopenDeal`, which records a reason.
+ *
+ * ── STILL TO COME (deliberately not stubbed) ────────────────────────────────────────────────────
+ *   - `DealStageEvent` append on ORDINARY stage transition, stamping `AmountAtTransition` and
+ *     `ProbabilityAtTransition`. `Sales.CloseDeal` already stamps the CLOSE transition; consolidating
+ *     the two into a single writer here is D-BD2. It must be inside the graph's transaction, which
+ *     since MJ `47ff71d68b` means a scope opened around `super.Save()` rather than a graph-node
+ *     branch — see the note on {@link DealEntityServer.Save}.
+ *
+ * @module @mj-biz-apps/sales-core-entities-server
+ */
+import { EntitySaveOptions } from '@memberjunction/core';
+import { DealEntity } from '@mj-biz-apps/sales-entities';
+/**
+ * The persisted state a deal held on the way OUT of a stage — what `DealStageEvent` records.
+ *
+ * A snapshot rather than a read at write time, because by then `super.Save()` has overwritten the
+ * values. See {@link DealEntityServer.planStageEvent}.
+ */
+/**
+ * The kinds of governed transition a remote operation can declare. Both are transactional acts that own
+ * their own provenance — `Sales.CloseDeal` and `Sales.ReopenDeal`. An ordinary stage move declares
+ * nothing; it is detected, not announced.
+ */
+export type DealTransitionKind = 'Close' | 'Reopen';
+export declare class DealEntityServer extends DealEntity {
+    /**
+     * Async validation always runs on this path. The base class defaults to skipping it; a deal that
+     * carries a whole graph of children is exactly the case where you want it, and silently skipping
+     * validation on the one code path every write takes would defeat the point of putting rules here.
+     */
+    get DefaultSkipAsyncValidation(): boolean;
+    /**
+     * Prepares the deal, then hands the whole graph to the framework.
+     *
+     * ── THIS METHOD RUNS EXACTLY ONCE PER SAVE, COMPOSITE OR NOT. ──
+     *
+     * That is a guarantee of MJ's, not an accident of ours, and it is worth knowing why because it used
+     * to be false. When a deal has children, `BaseEntity.Save()` builds a save plan and routes to
+     * `saveGraph`, which opens the transaction and executes every node — **the root included** — through
+     * the private `BaseEntity.saveAsGraphNode`, which calls `_InnerSave` directly:
+     *
+     *     SaveSelfOnly: (entity, opts) => entity.saveAsGraphNode(opts)
+     *
+     * `_InnerSave` is BELOW this override, so the graph never re-enters `Save()`. Preparation therefore
+     * happens once by construction, on the only call there is, and a childless deal (which never builds
+     * a plan at all) takes the same single path.
+     *
+     * ── DO NOT RE-ADD A GRAPH-NODE GUARD ──
+     *
+     * Until MJ `47ff71d68b` the graph executed the root by calling this record's public `Save()` again
+     * with `EntitySaveOptions.IsGraphNodeSave` set, so this method DID run twice and needed an early
+     * return to stay idempotent. MJ deleted that flag deliberately — *"so application code cannot skip
+     * companions by passing a public flag"* — and made the node path private. There is no successor
+     * property and none is wanted: the re-entrancy the guard defended against no longer happens.
+     *
+     * `EntitySaveOptions.SkipRelatedCollections` is NOT that successor. It suppresses the caller's own
+     * collections on the way in (orders' `OrderEntityServer` uses it to hold its lines back until the
+     * header has a key); it says nothing about who is calling. Reaching for it here would skip the
+     * deal's lines and team entirely.
+     *
+     * ── WHERE THE S4 STAGE-EVENT APPEND HAS TO GO (this changed too) ──
+     *
+     * `DealStageEvent` is append-only provenance, so a rolled-back save must not leave an event behind
+     * claiming a transition that did not happen — the append has to be inside the same transaction as
+     * the write. The old answer was "put it in the `IsGraphNodeSave` branch", because that branch ran
+     * inside the graph's transaction. **That branch is gone, and code placed here now runs BEFORE the
+     * graph opens anything.**
+     *
+     * The mechanism that still works is the one {@link DealEntityServer.saveWithinScope} uses: open a
+     * scope with `BeginEntityTransaction()`, do the work, then call `super.Save(options)` inside it. The
+     * graph's own scope JOINS an ambient transaction rather than opening a second one, so the append and
+     * every row in the graph commit or roll back together.
+     *
+     * **That append now exists** (D-BD2) and shares its scope with two other jobs. `saveWithinScope` is
+     * where the ordering between them is decided and is the only place this class opens a transaction.
+     */
+    Save(options?: EntitySaveOptions): Promise<boolean>;
+    private saveDeclared;
+    /**
+     * The snapshot an ordinary stage move owes the append-only log, or null when the deal did not move.
+     *
+     * ── THE PERSISTED VALUES, read before the save overwrites them ──
+     *
+     * `OldValue` is what is on disk, which is the only thing that makes a transition detectable — the
+     * same discipline the close lock uses when it asks whether the deal was ALREADY locked rather than
+     * whether it is about to be.
+     *
+     * ── THE STAMPS COME FROM THE PRIOR VALUES, NOT THE NEW ONES ──
+     *
+     * That is the whole point of the table. A board drag applies the target stage's probability default,
+     * so reading the current value here would record the number the deal acquired by ARRIVING rather
+     * than the one it held on the way out — and every velocity report built on it would be quietly
+     * wrong.
+     *
+     * A brand-new deal has no prior stage and owes no event: `priorStageID` is null, so it is not a
+     * MOVE. It is a birth, and `DealStageEvent` is a log of movement.
+     */
+    private planStageEvent;
+    /**
+     * The ONE place a save opens a transaction, and the one place the ordering is decided.
+     *
+     * Four jobs share this scope, and each has a reason to be where it is:
+     *
+     * 1. **The deal number**, BEFORE the header is written — `DealNumber` carries a filtered UNIQUE
+     *    index, and assigning it afterwards would mean a second write to a row already visible. The
+     *    transaction is what keeps the counter gap-free: `spAssignNextDealNumber` increments a locked
+     *    row, so a save that then fails must roll the increment back.
+     * 2. **The order status**, BEFORE the header is written, because an unsaved order is INSERTED in the
+     *    target status rather than created and then moved — one row, one state, no history of a status
+     *    it was never really in.
+     * 3. **The stage event**, AFTER, because it is provenance for a move that has actually happened.
+     *    An event for a save that then failed is worse than no event: it is a claim about history.
+     * 4. **The `Deal.Amount` cache**, LAST, because `OrderHeader.TotalGross` is trigger-maintained and
+     *    only reflects this save's lines once they are written. Its trigger is the ORDER changing rather
+     *    than the stage, which is why the caller decides separately whether it runs.
+     *
+     * **BOTH-OR-NEITHER, ACROSS ALL THREE.** A moved deal with no event is a hole in an append-only
+     * log. A numbered deal that does not exist consumes a number nobody can account for. And a stage
+     * change visible while the order it moved is not would be a worse outcome than either alone.
+     *
+     * `BeginEntityTransaction` JOINS an ambient transaction rather than opening a second, so a caller
+     * already in one — `Sales.CloseDeal`, or an integration check — gets a savepoint and everything
+     * still settles together.
+     *
+     * **A save with nothing to do here takes no transaction at all** (see the caller). The overwhelming
+     * majority of deal saves are edits to a field nobody is watching, and wrapping those in a scope
+     * would be a cost paid on every keystroke for a guarantee they do not need.
+     */
+    private saveWithinScope;
+    /**
+     * Writes the one `DealStageEvent` a move owes.
+     *
+     * APPEND-ONLY — never edited, never deleted. Note what is NOT here: no close, no routing, no
+     * downstream call. A stage change is a stage change; closing is `Sales.CloseDeal` and stays an
+     * explicit act, even when the stage a deal moves into is the one a pipeline calls Signed.
+     */
+    private appendStageEvent;
+    /**
+     * Gives a brand-new deal its embedded order, in Draft, on the deal's FIRST save.
+     *
+     * ── WHY THE ENTITY SERVER AND NOT THE WORKSPACE ──
+     *
+     * The workspace called `OrderID_EnsureObject()` from `AddLine()`, so a deal only got an order when
+     * somebody added a line THROUGH THE UI. An agent, an importer, a remote operation or a plain
+     * `BaseEntity.Save()` each produced a deal with no order at all -- and S-US4 puts the order at
+     * creation, not at first line. Same reasoning as the close lock below: a rule the UI enforces holds
+     * only until something that is not the UI writes.
+     *
+     * ── WHY FIRST SAVE AND NOT NewRecord() ──
+     *
+     * `OrderHeader.CompanyID` is NOT NULL, and a deal does not know its company until
+     * `stampCompanyFromPipeline()` has run: the caller supplies a PipelineID and the selling company is
+     * derived from it (D-4). Provisioning in `NewRecord()` would mean inventing a company or building an
+     * order that cannot be inserted. So it happens here, after the stamps, on the one call where
+     * `IsSaved` is still false.
+     *
+     * ── WHY THE GUARD IS `IsSaved`, AND NOT `IsSaved || OrderID` ──
+     *
+     * It was the second form, and that was a real bug rather than a stylistic choice. `Ensure()` assigns
+     * the new peer's key to `OrderID` immediately, so a caller that reached the order BEFORE saving --
+     * the workspace's `AddLine()`, an importer building a deal and its lines for one `Save()`, or any of
+     * the line checks in `save-deal` -- arrived here with `OrderID` already populated. The guard then
+     * returned early, the stamps below never ran, and the save died inside orders on
+     * `CompanyID cannot be null`: a NOT NULL complaint about a column two apps away from the mistake.
+     *
+     * Idempotent twice over all the same: `Ensure()` returns any existing peer, `IsSaved` means a re-save
+     * never re-provisions, and an order that is ALREADY PERSISTED is left untouched (below) so attaching
+     * an existing order stays a legitimate thing to do.
+     *
+     * ── WHAT SALES STATES, AND WHAT IT DOES NOT ──
+     *
+     * Company, type, and who to bill. NOT a status: orders' own `NewRecord()` defaults it to Draft, and
+     * restating that here would be sales asserting an order lifecycle it does not own. NOT an
+     * `OrderNumber`: the server subclass in orders mints it, which is what the diagnostic below is about.
+     *
+     * `BillToOrganizationID` and `BillToPersonID` are BOTH set, and unlike the contract case that is
+     * legal -- `OrderHeader` has no XOR across them, checked against `sys.check_constraints`. Do not
+     * carry the contract's exactly-one rule across by analogy; it is that table's rule, not a house style.
+     * `Deal.AccountID` is a `SalesAccount`, an IsA child of common's `Organization`, so its key IS an
+     * organization key; `PrimaryContactID` is a `SalesContact`, an IsA child of `Person`.
+     */
+    private provisionEmbeddedOrder;
+    /**
+     * Turns the one failure this provisioning can cause into a message that names its cause.
+     *
+     * `OrderNumber` is NOT NULL and is minted by the SERVER subclass in orders. If that class is not
+     * registered in the process, `ClassFactory` resolves the generated `OrderHeader` instead, nothing
+     * mints a number, and the insert dies on a NOT NULL violation raised inside the save graph. What
+     * reaches the caller is `Save failed for OrderID_Object (MJ_BizApps_Orders: Order Headers): Error
+     * executing SQL` -- which names the entity, not the reason, and reads like a database fault rather
+     * than a missing import.
+     *
+     * SALES MUST NOT FIX THAT BY DEPENDING ON ORDERS' SERVER PACKAGE. Neither `sales-server` nor
+     * `sales-core-entities-server` does, and neither should start: loading another app's server classes
+     * from inside this one is how two registrations for one key end up decided by import order. MJAPI
+     * owns that -- MJ declares orders' server packages itself, which is why the running app works. A
+     * bare node harness has to call `LoadBizAppsOrdersServer()` on its own.
+     *
+     * So this cannot repair anything. It exists to stop the next person debugging the wrong layer.
+     */
+    private explainOrderProvisioningFailure;
+    /**
+     * Warnings from the last `Save()` about what did NOT happen to the order, and why.
+     *
+     * A channel rather than a thrown error, because that is the whole ruling: *"The Deal stage is the
+     * salesperson's record of the sales process; it should never be held hostage by order-side rules"*
+     * (Andrew, D-OS1). So a refused order update is not a failure of the save — it is a fact about the
+     * save, and something has to be able to say it out loud.
+     *
+     * `Sales.ReopenDeal` and `Sales.CloseDeal` copy these into their `Issues` with
+     * `Severity: 'warning'`, which is how a caller sees them. A plain `deal.Save()` from the board's
+     * drag leaves them here and in the server log; see `DECISIONS-NEEDED.md` DN-12, because a warning
+     * only a server log carries is one a rep never reads.
+     */
+    private readonly _orderStatusWarnings;
+    get OrderStatusWarnings(): readonly string[];
+    /**
+     * Resolves what this save's stage change asks of the order. Reads only; opens nothing.
+     *
+     * ── WHAT COUNTS AS "CHANGING STAGE" ──
+     *
+     * `OldValue` versus the current value, the same mechanism {@link checkCloseLock} keys on. A save
+     * that does not touch `PipelineStageID` plans nothing, so an ordinary edit — a rename, a nudge to
+     * `NextStep` — never reaches the order. That matters more than it looks: an order that got
+     * re-Quoted on every save of its deal would be a write amplification nobody asked for, and on a
+     * Confirmed order it would be a refusal warning on every single save.
+     *
+     * A BRAND-NEW deal also counts as entering its first stage. `CanTransition` treats a null `from` as
+     * "may be created in any legal state", so a new deal on a stage naming `Quoted` gets an order
+     * created Quoted rather than created Draft and then moved — one row, one state, no history of a
+     * status it was never really in.
+     */
+    /**
+     * What the stage says this deal's probability and forecast category become — read BEFORE the
+     * transaction, like every other plan in this class.
+     *
+     * ── WHY THIS IS ON THE WRITE PATH AND NOT IN THE WORKSPACE ──────────────────────────────────
+     *
+     * It was in the workspace: `DealWorkspaceComponent.ApplyStageDefaults`, called from the stage picker.
+     * So a stage set by an agent, by the S6 HubSpot importer, by an Action or by any API caller got
+     * NEITHER value — the deal landed with whatever probability the caller happened to supply, or null,
+     * while the pipeline designer's answer sat unused in the stage row. Exactly the shape of the order
+     * provisioning that used to live in the workspace and now lives in `Save()`: a rule the UI enforces
+     * is a rule only the UI obeys.
+     *
+     * ── SAME TRIGGER AS THE OTHER THREE, DELIBERATELY A SEPARATE READ ───────────────────────────
+     *
+     * Keyed on `PipelineStageID` changing, like the order-status writer and the stage event. It reads the
+     * stage row a second time rather than widening `planStageOrderStatus`, and that is a considered
+     * trade: one extra read on a stage change — a rare event — against touching a method whose exact
+     * behaviour is pinned by `close-won-order.CO3`, `CO5` and three mutants. Cheap insurance beats a
+     * clever saving here.
+     *
+     * ── IT DOES NOT FIRE ON PROVISIONING, unlike the order-status writer ────────────────────────
+     *
+     * `planStageOrderStatus` also runs when an existing deal acquires an order (`_orderJustProvisioned`,
+     * SD25), because an order that has just come into existence has never been told anything. These
+     * fields are different: the deal has held them all along, and re-applying a stage default to a deal
+     * whose stage did not move would overwrite a number a rep tuned by hand.
+     */
+    private planStageDefaults;
+    /**
+     * Fills the forecast fields from the stage, WITHOUT overwriting a value this save set deliberately.
+     *
+     * ── THE RULE IS THE AMOUNT CACHE'S RULE ─────────────────────────────────────────────────────
+     *
+     * `Deal.Amount` distinguishes a computed figure from a stated one and never overwrites the stated
+     * one (SD22). The same distinction applies here and is read the same way: a field the caller TOUCHED
+     * in this save is theirs, and a field they did not touch is the stage's to fill.
+     *
+     * `Dirty` is what expresses that. It is true only when this save changed the value, so:
+     *
+     *   · A rep dragging a card sets no probability -> not dirty -> the stage's number lands.
+     *   · A rep who moves the stage AND types 85 -> dirty -> 85 stands, which is the point of the
+     *     workspace comment promising both stay editable.
+     *   · THERE IS NO UI COPY ANY MORE. The claim that stood here — that the workspace's own
+     *     `ApplyStageDefaults` set both fields before saving, so they arrived dirty and were respected,
+     *     so "the UI copy and this one cannot fight" — was WRONG, in the damaging direction. Arriving
+     *     dirty is precisely what made this method respect a number the UI had ALREADY overwritten.
+     *     Two copies did it, the workspace's and the board's, and BD6 stayed green because it drives the
+     *     entity layer and never touches either. Both are deleted; this is the only writer.
+     *   · An importer that supplies a historical probability keeps it; one that supplies none inherits
+     *     the pipeline's design instead of landing on null.
+     */
+    /**
+     * Did the CALLER put this value here in this save, or is it mine to fill?
+     *
+     * ── TWO OF MJ'S SEMANTICS BITE ON CREATE, AND THE ANSWER DIFFERS BECAUSE OF THEM ─────────────
+     *
+     * On an UPDATE, `Dirty` is exactly the question: it is true when this save changed the value.
+     *
+     * On a CREATE it is useless. A first assignment does not mark a field dirty, and the first write
+     * BECOMES the `OldValue` — so `Dirty` is false for a value the caller definitely supplied, and
+     * `OldValue` is a value that was never on disk. Asking `Dirty` on a new record therefore says "not
+     * theirs" about everything the caller just set.
+     *
+     * `applyStageDefaults` already knew this and guarded with `creating = !this.IsSaved`. Two other
+     * places did not, and both were wrong in the same direction:
+     *
+     *   · `planStageEvent` inferred a birth from `OldValue === null`. But a new deal whose stage is set
+     *     TWICE before the first save — `NewDeal()` preselects a pipeline and its first stage, the rep
+     *     then picks a different one — has a non-null `OldValue` holding a stage the deal was NEVER IN.
+     *     It appended a transition event for it, into an append-only log. `BD1` asserts against exactly
+     *     that and passes only because it assigns the stage once.
+     *   · `ownerStampEditRefusal` asked `Dirty`, so an importer doing `NewRecord()` ->
+     *     `OwnerEmployeeID = X` -> `Save()` slipped straight through the refusal and created a deal whose
+     *     owner column and owner-role roster name different people — the state SD26 exists to forbid.
+     *
+     * So the question lives here now, once, and the callers ask it rather than each re-deriving it.
+     */
+    private callerSuppliedValue;
+    private applyStageDefaults;
+    /**
+     * The status a BRAND-NEW deal starts in when nothing else supplied one.
+     *
+     * ── WHY A DEAL WITH NO STATUS IS WORSE THAN A DEAL WITH A WRONG ONE ──────────────────────────────
+     *
+     * `Deal.DealStatusTypeID` is nullable with no column default, and until now nothing in the write path
+     * required it. A deal saved without touching Status landed NULL, and every measure that reads the
+     * status through `JOIN DealStatusType` silently did not count it — a tile that under-reports rather
+     * than one that errors. It also cost a misdiagnosis: `71-lost-and-reopen` failed with
+     * `Cannot read properties of undefined (reading 'IsLost')`, which reads as a bad field and was the
+     * JOIN dropping the row.
+     *
+     * ── NEVER DERIVED FROM THE STAGE, AND THE NUMBERS SAY WHY ────────────────────────────────────
+     *
+     * The obvious-looking fix — take the stage's status — closes deals by side effect. Measured on this
+     * host: `Booked` → Won, `Signed` → Won and `Lost` → Lost all carry `LocksDeal = 1`. A deal created
+     * in one of those stages would be born closed and locked, and a board drag would book revenue. That
+     * is why {@link planStageDefaults} gates its own stage-derived status on `LocksDeal`, and why this
+     * fallback asks the VOCABULARY what an opening status is instead of asking the stage.
+     *
+     * ── THE THIRD CONDITION IS NOT REDUNDANT ────────────────────────────────────────────────────
+     *
+     * `IsActive = 1 AND IsOpen = 1 AND LocksDeal = 0`. Today every `IsOpen = 1` row also has
+     * `LocksDeal = 0`, so the third term selects nothing extra — but that is a property of the seeded
+     * data, not an invariant the schema enforces. Nothing stops a tenant declaring an open status that
+     * also locks, and since the entire hazard here is closing a deal by side effect, the guard says so
+     * rather than relying on the coincidence holding.
+     *
+     * `DisplayRank` makes the choice deterministic when a tenant defines several opening statuses.
+     *
+     * ── AND IT LEAVES NULL RATHER THAN REFUSING ──────────────────────────────────────────────────
+     *
+     * If no active, open, non-locking status exists the vocabulary is misconfigured — but refusing the
+     * save would block ALL deal creation on that tenant, which is a worse failure than the gap being
+     * closed. Returning null preserves exactly today's behaviour for that case and nothing more.
+     */
+    private defaultOpeningStatusID;
+    private planStageOrderStatus;
+    /**
+     * Applies the plan to the deal's order, and NEVER lets a refusal reach the caller as a failure.
+     *
+     * ── WHY THE TRANSITION IS CHECKED BEFORE IT IS ATTEMPTED ──
+     *
+     * `CanTransition` is orders' own table of legal moves. Asking it first means the ordinary refusal —
+     * `Voided → Quoted` on a reopened lost deal, which S-US8 says WILL happen — costs no write and
+     * produces orders' own explanation. Attempting the save and reading the failure would also work,
+     * but it would leave the in-memory order holding a status the database refused, and that object is
+     * a participant in this deal's save graph.
+     *
+     * ── WHY THE SAVE STILL RUNS IN ITS OWN SCOPE ──
+     *
+     * A legal transition can still fail for reasons this app does not model — confirming books journal
+     * entries and needs a payer. `BeginEntityTransaction` joins the ambient transaction as a savepoint,
+     * so rolling this one back undoes the order write and leaves the deal's own transaction intact.
+     * Without that, one order-side failure would take the stage change down with it, which is exactly
+     * what D-OS1 forbids.
+     *
+     * ── THE UNSAVED ORDER ──
+     *
+     * A new deal's order has not been written yet, so there is nothing to transition and nothing to
+     * roll back: setting `Status` means it is INSERTED in that state by the graph a moment later.
+     */
+    private applyStageOrderStatus;
+    /**
+     * Re-establishes `Deal.Amount` from the order, as a CACHE with honest provenance.
+     *
+     * ── WHAT BROKE, AND WHY IT WAS INVISIBLE ──
+     *
+     * `Amount` was a cached `Orders.PreviewOrder` answer and `AmountSourceHash` fingerprinted the
+     * `DealLine` set it came from. `DealLine` is retired, so the fingerprint describes a table that does
+     * not exist and NOTHING repopulated the number. It did not go blank — it kept whatever it last held,
+     * which is the failure mode that survives review: a dashboard and a board reporting a pipeline
+     * figure with no relationship to the order underneath it.
+     *
+     * ── WHY `OrderHeader.TotalGross` AND NOT A SUM HERE ──
+     *
+     * Rule 1. Orders maintains `TotalGross` with its own rollup trigger (their D41 —
+     * trigger-maintained, deliberately not a computed column), so this reads ONE number that orders
+     * already stands behind. There is no multiplication, no addition and no rounding in this method, and
+     * there must never be: the moment sales sums `LineTotalGross` itself, the quote and the invoice can
+     * disagree.
+     *
+     * ── WHY IT IS CACHED ONTO THE DEAL ──
+     *
+     * The roster and the board read `Deal.Amount` as a column. Reading through the embedded order per
+     * row would turn one roster query into one-plus-N, on the hottest read in the app. Same argument as
+     * `OwnerEmployeeID`: a denormalised stamp exists so a list does not need a join.
+     *
+     * ── WHY IT RUNS LAST, INSIDE THE SCOPE ──
+     *
+     * `TotalGross` is trigger-maintained, so the value only reflects this save's lines AFTER
+     * `super.Save()` has written them. Reading earlier caches the PREVIOUS line set — the exact staleness
+     * this method exists to end. It writes with a targeted `UPDATE` rather than a second `Save()`: the
+     * row is already written in this transaction, and re-entering `Save()` would re-run the close lock,
+     * the stamps and the stage-event planner for a three-column cache refresh.
+     *
+     * ── THE PROVENANCE RULE, WHICH IS THE PART TO GET RIGHT ──
+     *
+     * `AmountIsComputed = 0` means a human typed this figure and is owed no explanation (L-2, the SIMPLE
+     * deal). Such an amount is NEVER overwritten. But the column defaults to 0, so "0" alone cannot mean
+     * hand-typed — a brand-new deal has never been touched by anyone. The distinction is whether an
+     * amount is actually THERE:
+     *
+     *   | `AmountIsComputed` | `Amount` | what it means | what happens |
+     *   |---|---|---|---|
+     *   | 1 | anything | a cache | refreshed |
+     *   | 0 | NULL | nobody has said | filled, and marked computed |
+     *   | 0 | a number | **a human typed it** | **left alone, always** |
+     *
+     * And a `TotalGross` of NULL means the order has no priced lines, so there is no answer to cache —
+     * that leaves the amount alone too, rather than writing a zero that would read as "priced at nil".
+     */
+    private refreshAmountFromOrder;
+    /**
+     * Set only for the duration of {@link BeginReopen}, which is the ONE audited path through the lock.
+     *
+     * Deliberately NOT public: a caller that could set this could bypass the lock, which would make the
+     * lock advisory. `Sales.ReopenDeal` records a reason; nothing else may get through.
+     */
+    private _reopenInProgress;
+    /**
+     * True when THIS save built the deal's order, rather than finding one already there.
+     *
+     * It exists so the stage's `OrderStatusOnEntry` can be applied to an order that has just come into
+     * existence. The status writer otherwise keys on `PipelineStageID` CHANGING, which is right for a
+     * move and wrong for a birth: a deal that is already at Proposal when its order is provisioned
+     * never moved, so nothing asked the stage what the order should be, and the order stayed Draft
+     * while its stage plainly declared Quoted. Found by the story audit against seeded data
+     * (`DEAL-9003`), and it would have hit every deal the HubSpot import lands past Proposal.
+     */
+    private _orderJustProvisioned;
+    /**
+     * Whether the PERSISTED status locks this deal — set by {@link checkCloseLock} on every save.
+     *
+     * The lock used to answer one question ("may this edit proceed?") and nothing else, so the writers
+     * further down the save could not tell a frozen deal from a live one. `provisionEmbeddedOrder` in
+     * particular ran unconditionally, and Description is deliberately editable while locked — so editing
+     * the description of a closed legacy deal INSERTED an empty Draft order, rewrote `Deal.OrderID` on a
+     * frozen row, and let the stage writer stamp that order from the CLOSING stage (`Voided`, for a lost
+     * deal). Every one of those is a write to provenance that is supposed to be immutable.
+     *
+     * So the lock now reports what it found. Nothing else may recompute it: two places deciding whether a
+     * deal is locked is how they come to disagree.
+     */
+    /**
+     * ── ONE WRITER FOR THE STAGE LOG, AND CALLERS DECLARE INSTEAD OF WRITING ────────────────────────
+     *
+     * `PipelineStageID` had FOUR writers by the end of the last round — this class's event appender and
+     * defaults applier, plus `Sales.CloseDeal` and `Sales.ReopenDeal`, each hand-writing a
+     * `DealStageEvent` and then moving the stage. The sequence was never audited whole, and all three
+     * consequences were of the same kind:
+     *
+     *   · **Two rows for one transition.** `stampClose` wrote its event, then set
+     *     `deal.PipelineStageID = input.ClosingStageID`, and the save that followed saw a stage change and
+     *     appended a SECOND row. `close-deal.CD4` could not see it because it never passes
+     *     `ClosingStageID` — the only input that makes the stage move. Reopen had it too, identically.
+     *   · **A self-transition.** `planStageEvent` compared stage ids case-sensitively while the two
+     *     writers beside it lowercased first, so a caller that normalised its ids got an append-only row
+     *     saying the deal moved from a stage to itself.
+     *   · **A reopen losing its probability.** `ReopenDeal` passing a `StageID` silently invoked the
+     *     DEFAULTS writer, which re-derived `Probability` from the arriving stage — after the reopen
+     *     event had already stamped the old one. The stamp said 60 and the deal said 10.
+     *
+     * The fix is not a fourth special case behind a wider gate. A caller now DECLARES that this save is a
+     * governed transition and supplies the note that belongs on it; the entity remains the only thing that
+     * writes to `DealStageEvent`, and it reads the declaration to answer the two questions the callers
+     * were each answering for themselves:
+     *
+     *   · **Is an event owed?** Yes if the stage moved — and also yes if a transition is declared, which
+     *     is what makes a close that does NOT move the stage still leave provenance. That case was the
+     *     reason `stampClose` wrote its own row in the first place.
+     *   · **Do the stage's defaults apply?** No. A declared transition's probability is the caller's
+     *     considered value — a close's final number, a reopen's hand-tuned one — and re-deriving it from
+     *     the pipeline would overwrite the very figure the event just stamped.
+     *
+     * Declared per save and cleared when it finishes, like every other per-save field here: a declaration
+     * that outlived its save would silently suppress the defaults on the next unrelated edit.
+     */
+    DeclareTransition(kind: DealTransitionKind, note: string | null): void;
+    /** The id of the `DealStageEvent` the last save appended, or null if it owed none. */
+    get LastStageEventID(): string | null;
+    private _declaredTransition;
+    private _lastStageEventID;
+    private _lockedAtSave;
+    /**
+     * The fields that stay editable on a locked deal — read from the SHARED rule, not redeclared.
+     *
+     * It moved to `@mj-biz-apps/sales-entities` so the Explorer Deal form can apply the same list. A
+     * second copy here would drift, and the drift would only ever surface as a user typing into a field
+     * the server then refuses. See `close-lock.ts` for the reasoning; CD14 pins it to real behaviour.
+     */
+    private static readonly LOCK_EDITABLE_FIELDS;
+    /**
+     * Runs `body` with the close lock suppressed, and always restores it.
+     *
+     * The `finally` is the point: an exception inside the reopen must not leave the lock disabled for
+     * the rest of this entity's life, which would silently turn every later save into an unguarded one.
+     */
+    BeginReopen<T>(body: () => Promise<T>): Promise<T>;
+    /**
+     * Why this save is refused, or null if it is allowed.
+     *
+     * KEYED ON THE **PERSISTED** STATUS, via `OldValue` — not on the in-memory one. That is what makes
+     * the closing transition itself legal: a deal moving open → closed still has an OPEN status in the
+     * database, so it passes, and only saves made once the deal is ALREADY closed are refused. Reading
+     * the current value instead would make a deal impossible to close.
+     */
+    private checkCloseLock;
+    /**
+     * Whether a status carries `LocksDeal`.
+     *
+     * THE FLAG, never the name — a deployment may call its winning status "Signed", and this must keep
+     * working. It is also why the lock is a property of the STATUS TYPE rather than of the stage.
+     */
+    private statusLocksDeal;
+    /**
+     * Forces `Deal.CompanyID` to the pipeline's company, ignoring whatever the caller supplied.
+     *
+     * THE PIPELINE IS THE ONLY SOURCE THAT CAN BE RIGHT. A deal belongs to the company that owns the
+     * pipeline it sits in, and a CHECK constraint cannot express that — it cannot reach across the
+     * foreign key to compare the two. So it is resolved on the write path instead, on every save, for
+     * every caller.
+     *
+     * An explicitly supplied value is OVERWRITTEN rather than rejected. A client that gets this wrong is
+     * not making a choice the app should honour or argue with; it is stating something it has no standing
+     * to know, and the correct answer is available here.
+     *
+     * A missing pipeline is left alone: `Validate()` already refuses a deal without one, and raising a
+     * second, vaguer complaint here would just bury the specific message the user needs.
+     */
+    private stampCompanyFromPipeline;
+    /**
+     * Maintains `Deal.OwnerEmployeeID` from whichever team member holds the owner role.
+     *
+     * `SetOwner` — the intent-expressing half — is on {@link DealEntity}, because the workspace's owner
+     * picker has to express the same thing. What is server-only is this: keeping the DENORMALIZED stamp
+     * true. `DealTeamMember` is the source of truth; the stamp exists only so "my deals" and per-rep
+     * boards need no join, and nothing outside this hierarchy may write it.
+     *
+     * GUARDED ON THE COLLECTION BEING AUTHORITATIVE, which is the whole subtlety. A save that never
+     * touched the roster has an empty, never-loaded `Team` — and deriving "no owner" from that would
+     * silently CLEAR the stamp on every ordinary header edit. So the stamp is only rewritten when the
+     * collection was actually loaded, or actually appended to.
+     *
+     * Both conditions are needed because `Add()` and `Create()` do not mark a collection loaded: a new
+     * deal whose roster was composed in the browser arrives with `IsLoaded === false` and `Count > 0`.
+     */
+    /**
+     * Why a direct write to `OwnerEmployeeID` is refused, or null when this save is not doing that.
+     *
+     * ── THE HOLE THIS CLOSES, AND WHY IT WAS NOT OBVIOUS ────────────────────────────────────────
+     *
+     * {@link stampOwnerFromTeam} is guarded on the roster having participated in the save, and that
+     * guard is correct — without it, an ordinary header edit would derive "no owner" from an unloaded
+     * collection and CLEAR the stamp. But its consequence was two paths and a refusal on neither: a
+     * save carrying the roster silently DISCARDED a hand-set stamp, and a header-only save silently
+     * KEPT one. The second is the damaging half. It left the app able to hold a deal whose owner column
+     * and owner-role team row name different people, reached by a plain `BaseEntity.Save()` with no
+     * error and no warning — and the stamp exists precisely so per-rep rollups need no join, so a
+     * rollup could disagree with the roster it was meant to shortcut. Proven against the database by
+     * `scripts/audit-story-evidence.mjs` (E3) before this existed.
+     *
+     * ── WHY REFUSE RATHER THAN QUIETLY RE-DERIVE ────────────────────────────────────────────────
+     *
+     * Because the caller believed they were setting the owner. Correcting them in silence produces the
+     * same wrong outcome as before — the owner is not who they said — with no way to notice. The
+     * message names {@link DealEntity.SetOwner}, which is the operation they actually wanted.
+     *
+     * ── WHY `SetOwner` IS NOT CAUGHT BY THIS ────────────────────────────────────────────────────
+     *
+     * It calls `Team.Load()` first, so `IsLoaded` is true by the time it assigns the stamp: the roster
+     * IS part of that save, and the server re-derives the same value from it a moment later. The two
+     * conditions mirror `stampOwnerFromTeam`'s guard exactly, which is what keeps them from disagreeing.
+     */
+    private ownerStampEditRefusal;
+    private stampOwnerFromTeam;
+}
+//# sourceMappingURL=DealEntityServer.d.ts.map

package/dist/DealEntityServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DealEntityServer.d.ts","sourceRoot":"","sources":["../src/DealEntityServer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,OAAO,EAGH,iBAAiB,EAIpB,MAAM,sBAAsB,CAAC;AAQ9B,OAAO,EAEH,UAAU,EAEb,MAAM,6BAA6B,CAAC;AA0DrC;;;;;GAKG;AACH;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,QAAQ,CAAC;AAqBpD,qBACa,gBAAiB,SAAQ,UAAU;IAC5C;;;;OAIG;IACH,IAAoB,0BAA0B,IAAI,OAAO,CAExD;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;IACmB,IAAI,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;YAyB3D,YAAY;IAmL1B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,cAAc;IAmDtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;YACW,eAAe;IAyI7B;;;;;;OAMG;YACW,gBAAgB;IAqD9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,OAAO,CAAC,sBAAsB;IAmC9B;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,+BAA+B;IAgBvC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAgB;IAErD,IAAW,mBAAmB,IAAI,SAAS,MAAM,EAAE,CAElD;IAED;;;;;;;;;;;;;;;OAeG;IACH;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;YACW,iBAAiB;IA2F/B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,kBAAkB;IAmE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;YACW,sBAAsB;YAoBtB,oBAAoB;IAmDlC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;YACW,qBAAqB;IA2DnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;YACW,sBAAsB;IA8HpC;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB,CAAS;IAElC;;;;;;;;;OASG;IACH,OAAO,CAAC,qBAAqB,CAAS;IAEtC;;;;;;;;;;;;OAYG;IACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACI,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI7E,sFAAsF;IACtF,IAAW,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAE3C;IAED,OAAO,CAAC,mBAAmB,CAAmC;IAC9D,OAAO,CAAC,iBAAiB,CAAuB;IAChD,OAAO,CAAC,aAAa,CAAS;IAE9B;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAqC;IAEjF;;;;;OAKG;IACU,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAS/D;;;;;;;OAOG;YACW,cAAc;IAkD5B;;;;;OAKG;YACW,eAAe;IAuB7B;;;;;;;;;;;;;;OAcG;YACW,wBAAwB;IA8BtC;;;;;;;;;;;;;;;OAeG;IACH;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,OAAO,CAAC,qBAAqB;YAef,kBAAkB;CASnC"}