@autologix-engineering/shared 1.2.385 → 1.2.387

package/src/lib/models/src/ltr.payout.model.js.map

@@ -1 +1 @@
-{"version":3,"file":"ltr.payout.model.js","sourceRoot":"","sources":["../../../../../../../libs/shared/src/lib/models/src/ltr.payout.model.ts"],"names":[],"mappings":"AASA,MAAM,CAAN,IAAY,cAgBX;AAhBD,WAAY,cAAc;IACzB,6CAA2B,CAAA;IAC3B,iDAA+B,CAAA;IAC/B,qCAAmB,CAAA;IACnB,yCAAuB,CAAA;IACvB,yCAAuB,CAAA;IACvB,mDAAiC,CAAA;IACjC,qDAAmC,CAAA;IACnC,uCAAqB,CAAA;IACrB,qCAAmB,CAAA;IACnB,mDAAiC,CAAA;IACjC,mCAAiB,CAAA;IACjB,iDAA+B,CAAA;IAC/B,uDAAqC,CAAA;IACrC,yDAAuC,CAAA;IACvC,+CAA6B,CAAA;AAC9B,CAAC,EAhBW,cAAc,KAAd,cAAc,QAgBzB;AAsCD,MAAM,CAAN,IAAY,iBAuEX;AAvED,WAAY,iBAAiB;IAC5B,oCAAe,CAAA;IACf,iEAA4C,CAAA;IAC5C,6DAAwC,CAAA;IACxC,iDAA4B,CAAA;IAC5B,yCAAoB,CAAA;IACpB,qCAAgB,CAAA;IAChB,wCAAmB,CAAA;IACnB,kCAAa,CAAA;IACb,wCAAmB,CAAA;IACnB,sCAAiB,CAAA;IACjB,+CAA0B,CAAA;IAC1B,wCAAmB,CAAA;IACnB,2CAAsB,CAAA;IACtB,iDAA4B,CAAA;IAC5B,yDAAoC,CAAA;IACpC,iDAA4B,CAAA;IAC5B,0EAAqD,CAAA;IACrD,uEAAkD,CAAA;IAClD,2CAAsB,CAAA;IACtB,8FAAyE,CAAA;IACzE,6GAAwF,CAAA;IACxF,qDAAgC,CAAA;IAChC,mDAA8B,CAAA;IAC9B,uDAAkC,CAAA;IAClC,6CAAwB,CAAA;IACxB,4DAAuC,CAAA;IACvC,qDAAgC,CAAA;IAChC,gEAA2C,CAAA;IAC3C,oEAA+C,CAAA;IAC/C,yDAAoC,CAAA;IACpC,oEAA+C,CAAA;IAC/C,wEAAmD,CAAA;IACnD,+CAA0B,CAAA;IAC1B,iDAA4B,CAAA;IAC5B,uDAAkC,CAAA;IAClC,yDAAoC,CAAA;IACpC,qDAAgC,CAAA;IAChC,yDAAoC,CAAA;IACpC,sDAAiC,CAAA;IACjC,iDAA4B,CAAA;IAC5B,qEAAgD,CAAA;IAChD,uEAAkD,CAAA;IAClD,0DAAqC,CAAA;IACrC,0DAAqC,CAAA;IACrC,sDAAiC,CAAA;IACjC,sDAAiC,CAAA;IACjC,kDAA6B,CAAA;IAC7B,kDAA6B,CAAA;IAC7B,4DAAuC,CAAA;IACvC,4DAAuC,CAAA;IACvC,sDAAiC,CAAA;IACjC,wDAAmC,CAAA;IACnC,4CAAuB,CAAA;IACvB,4CAA4C;IAC5C,oDAA+B,CAAA;IAC/B,gDAA2B,CAAA;IAC3B,iEAA4C,CAAA;IAC5C,mEAA8C,CAAA;IAC9C;;;;;;;;;;OAUG;IACH,wCAAmB,CAAA;AACpB,CAAC,EAvEW,iBAAiB,KAAjB,iBAAiB,QAuE5B"}
+{"version":3,"file":"ltr.payout.model.js","sourceRoot":"","sources":["../../../../../../../libs/shared/src/lib/models/src/ltr.payout.model.ts"],"names":[],"mappings":"AASA,MAAM,CAAN,IAAY,cAgBX;AAhBD,WAAY,cAAc;IACzB,6CAA2B,CAAA;IAC3B,iDAA+B,CAAA;IAC/B,qCAAmB,CAAA;IACnB,yCAAuB,CAAA;IACvB,yCAAuB,CAAA;IACvB,mDAAiC,CAAA;IACjC,qDAAmC,CAAA;IACnC,uCAAqB,CAAA;IACrB,qCAAmB,CAAA;IACnB,mDAAiC,CAAA;IACjC,mCAAiB,CAAA;IACjB,iDAA+B,CAAA;IAC/B,uDAAqC,CAAA;IACrC,yDAAuC,CAAA;IACvC,+CAA6B,CAAA;AAC9B,CAAC,EAhBW,cAAc,KAAd,cAAc,QAgBzB;AAsCD,MAAM,CAAN,IAAY,iBA2FX;AA3FD,WAAY,iBAAiB;IAC5B,oCAAe,CAAA;IACf,iEAA4C,CAAA;IAC5C,6DAAwC,CAAA;IACxC,iDAA4B,CAAA;IAC5B,yCAAoB,CAAA;IACpB,qCAAgB,CAAA;IAChB,wCAAmB,CAAA;IACnB,kCAAa,CAAA;IACb,wCAAmB,CAAA;IACnB,sCAAiB,CAAA;IACjB,+CAA0B,CAAA;IAC1B,wCAAmB,CAAA;IACnB,2CAAsB,CAAA;IACtB,iDAA4B,CAAA;IAC5B,yDAAoC,CAAA;IACpC,iDAA4B,CAAA;IAC5B,0EAAqD,CAAA;IACrD,uEAAkD,CAAA;IAClD,2CAAsB,CAAA;IACtB,8FAAyE,CAAA;IACzE,6GAAwF,CAAA;IACxF,qDAAgC,CAAA;IAChC,mDAA8B,CAAA;IAC9B,uDAAkC,CAAA;IAClC,6CAAwB,CAAA;IACxB;;;;;;;OAOG;IACH,wDAAmC,CAAA;IACnC,4DAAuC,CAAA;IACvC,qDAAgC,CAAA;IAChC,gEAA2C,CAAA;IAC3C,oEAA+C,CAAA;IAC/C,yDAAoC,CAAA;IACpC,oEAA+C,CAAA;IAC/C,wEAAmD,CAAA;IACnD,+CAA0B,CAAA;IAC1B,iDAA4B,CAAA;IAC5B,uDAAkC,CAAA;IAClC,yDAAoC,CAAA;IACpC,qDAAgC,CAAA;IAChC,yDAAoC,CAAA;IACpC,sDAAiC,CAAA;IACjC,iDAA4B,CAAA;IAC5B,qEAAgD,CAAA;IAChD,uEAAkD,CAAA;IAClD,0DAAqC,CAAA;IACrC,0DAAqC,CAAA;IACrC,sDAAiC,CAAA;IACjC,sDAAiC,CAAA;IACjC,kDAA6B,CAAA;IAC7B,kDAA6B,CAAA;IAC7B,4DAAuC,CAAA;IACvC,4DAAuC,CAAA;IACvC,sDAAiC,CAAA;IACjC,wDAAmC,CAAA;IACnC,4CAAuB,CAAA;IACvB;;;;;;;;;OASG;IACH,kDAA6B,CAAA;IAC7B,4CAA4C;IAC5C,oDAA+B,CAAA;IAC/B,gDAA2B,CAAA;IAC3B,iEAA4C,CAAA;IAC5C,mEAA8C,CAAA;IAC9C;;;;;;;;;;OAUG;IACH,wCAAmB,CAAA;AACpB,CAAC,EA3FW,iBAAiB,KAAjB,iBAAiB,QA2F5B"}

package/src/lib/models/src/ltr.payout.row.group.model.d.ts

@@ -22,6 +22,10 @@ export declare enum LTRPayoutRowGroupField {
     SignedOffAt = "signedOffAt",
     SignOffMethod = "signOffMethod",
     SignatureImageUrl = "signatureImageUrl",
+    /** When a submitted payout superseded this entry. Null while it is live. */
+    SupersededAt = "supersededAt",
+    /** Who submitted the payout that superseded it. */
+    SupersededByRegisteredUserId = "supersededByRegisteredUserId",
     CreatedAt = "createdAt",
     UpdatedAt = "updatedAt"
 }
@@ -68,6 +72,31 @@ export interface ILTRPayoutRowGroup {
     [LTRPayoutRowGroupField.SignOffMethod]?: LTRPayoutSignOffMethod;
     /** Set only when the daily sign-off captured a signature. */
     [LTRPayoutRowGroupField.SignatureImageUrl]?: string;
+    /**
+     * Set when a payout submitted for the booking superseded this entry.
+     *
+     * A submitted payout replaces whatever the driver logged, so from that
+     * moment the entry is no longer part of the booking's record: it stops
+     * counting toward the driver's month, stops being listed in the app, and
+     * stops appearing on the day-wise tab. Every reader filters on this, which
+     * is why the behaviour visible to a driver is the same as when these rows
+     * were deleted outright.
+     *
+     * It is a stamp rather than a DELETE because the two differ entirely in
+     * what they cost to get wrong. Superseding the wrong month is one UPDATE to
+     * undo; deleting it took the rows and their expense images with it, and
+     * nothing downstream could say afterwards what had been billed. Payout
+     * history is the thing an invoice dispute is settled from. (AD-3279)
+     */
+    [LTRPayoutRowGroupField.SupersededAt]?: Date;
+    /**
+     * Registered user of whoever submitted the superseding payout.
+     *
+     * Taken from the authenticated request, not the body: the question this
+     * answers is who did it, and only the token knows that. Absent on entries
+     * superseded before this was recorded.
+     */
+    [LTRPayoutRowGroupField.SupersededByRegisteredUserId]?: string;
     [LTRPayoutRowGroupField.CreatedAt]: Date;
     [LTRPayoutRowGroupField.UpdatedAt]: Date;
 }

package/src/lib/models/src/ltr.payout.row.group.model.js

@@ -19,6 +19,10 @@ export var LTRPayoutRowGroupField;
     LTRPayoutRowGroupField["SignedOffAt"] = "signedOffAt";
     LTRPayoutRowGroupField["SignOffMethod"] = "signOffMethod";
     LTRPayoutRowGroupField["SignatureImageUrl"] = "signatureImageUrl";
+    /** When a submitted payout superseded this entry. Null while it is live. */
+    LTRPayoutRowGroupField["SupersededAt"] = "supersededAt";
+    /** Who submitted the payout that superseded it. */
+    LTRPayoutRowGroupField["SupersededByRegisteredUserId"] = "supersededByRegisteredUserId";
     LTRPayoutRowGroupField["CreatedAt"] = "createdAt";
     LTRPayoutRowGroupField["UpdatedAt"] = "updatedAt";
 })(LTRPayoutRowGroupField || (LTRPayoutRowGroupField = {}));

package/src/lib/models/src/ltr.payout.row.group.model.js.map

@@ -1 +1 @@
-{"version":3,"file":"ltr.payout.row.group.model.js","sourceRoot":"","sources":["../../../../../../../libs/shared/src/lib/models/src/ltr.payout.row.group.model.ts"],"names":[],"mappings":"AASA,MAAM,CAAN,IAAY,sBAsBX;AAtBD,WAAY,sBAAsB;IACjC,mDAAyB,CAAA;IACzB,2CAAiB,CAAA;IACjB,+CAAqB,CAAA;IACrB,6CAAmB,CAAA;IACnB,iDAAuB,CAAA;IACvB,2CAAiB,CAAA;IACjB,2CAAiB,CAAA;IACjB,8CAA8C;IAC9C,iDAAuB,CAAA;IACvB,6CAA6C;IAC7C,6CAAmB,CAAA;IACnB,uEAAuE;IACvE,+CAAqB,CAAA;IACrB,2CAAiB,CAAA;IACjB,yDAAyD;IACzD,iFAAuD,CAAA;IACvD,qDAA2B,CAAA;IAC3B,yDAA+B,CAAA;IAC/B,iEAAuC,CAAA;IACvC,iDAAuB,CAAA;IACvB,iDAAuB,CAAA;AACxB,CAAC,EAtBW,sBAAsB,KAAtB,sBAAsB,QAsBjC"}
+{"version":3,"file":"ltr.payout.row.group.model.js","sourceRoot":"","sources":["../../../../../../../libs/shared/src/lib/models/src/ltr.payout.row.group.model.ts"],"names":[],"mappings":"AASA,MAAM,CAAN,IAAY,sBA0BX;AA1BD,WAAY,sBAAsB;IACjC,mDAAyB,CAAA;IACzB,2CAAiB,CAAA;IACjB,+CAAqB,CAAA;IACrB,6CAAmB,CAAA;IACnB,iDAAuB,CAAA;IACvB,2CAAiB,CAAA;IACjB,2CAAiB,CAAA;IACjB,8CAA8C;IAC9C,iDAAuB,CAAA;IACvB,6CAA6C;IAC7C,6CAAmB,CAAA;IACnB,uEAAuE;IACvE,+CAAqB,CAAA;IACrB,2CAAiB,CAAA;IACjB,yDAAyD;IACzD,iFAAuD,CAAA;IACvD,qDAA2B,CAAA;IAC3B,yDAA+B,CAAA;IAC/B,iEAAuC,CAAA;IACvC,4EAA4E;IAC5E,uDAA6B,CAAA;IAC7B,mDAAmD;IACnD,uFAA6D,CAAA;IAC7D,iDAAuB,CAAA;IACvB,iDAAuB,CAAA;AACxB,CAAC,EA1BW,sBAAsB,KAAtB,sBAAsB,QA0BjC"}

package/src/lib/models/src/numbered.invoice.model.d.ts

@@ -77,9 +77,21 @@ export declare enum NumberedInvoiceField {
     ConsolidatedTaxInvoiceId = "consolidatedTaxInvId",
     LTRKey = "ltrKey",
     LTRDataKey = "ltrDataKey",
+    LTRCoverageSnapshot = "ltrCovSnap",
     VendorTaxAddress = "vendorTaxAddress",
     VendorTaxAddressId = "vendorTaxAddressId"
 }
+/**
+ * The LTR vehicle master's LastInvoiceDateByGroup entries an LTR invoice moved
+ * when it was generated: `before` is each group's value going in (null when
+ * the group had never billed), `after` the value the invoice wrote. Cancelling
+ * the invoice restores `before`, so the months it billed become billable again.
+ */
+export interface ILTRCoverageSnapshot {
+    vehicleMasterId: string;
+    before: Record<string, string | null>;
+    after: Record<string, string>;
+}
 export interface INumberedInvoice extends TypedModel {
     [NumberedInvoiceField.NumberedInvoiceId]: string;
     [NumberedInvoiceField.InvoiceNumber]: string;
@@ -139,6 +151,7 @@ export interface INumberedInvoice extends TypedModel {
     [NumberedInvoiceField.ConsolidatedTaxInvoiceId]?: string;
     [NumberedInvoiceField.LTRKey]: string;
     [NumberedInvoiceField.LTRDataKey]: string;
+    [NumberedInvoiceField.LTRCoverageSnapshot]?: ILTRCoverageSnapshot | null;
     [NumberedInvoiceField.VendorTaxAddress]?: ITaxAddress;
     [NumberedInvoiceField.VendorTaxAddressId]?: string;
 }

package/src/lib/models/src/numbered.invoice.model.js

@@ -61,6 +61,7 @@ export var NumberedInvoiceField;
     NumberedInvoiceField["ConsolidatedTaxInvoiceId"] = "consolidatedTaxInvId";
     NumberedInvoiceField["LTRKey"] = "ltrKey";
     NumberedInvoiceField["LTRDataKey"] = "ltrDataKey";
+    NumberedInvoiceField["LTRCoverageSnapshot"] = "ltrCovSnap";
     NumberedInvoiceField["VendorTaxAddress"] = "vendorTaxAddress";
     NumberedInvoiceField["VendorTaxAddressId"] = "vendorTaxAddressId";
 })(NumberedInvoiceField || (NumberedInvoiceField = {}));

package/src/lib/models/src/numbered.invoice.model.js.map

@@ -1 +1 @@
-{"version":3,"file":"numbered.invoice.model.js","sourceRoot":"","sources":["../../../../../../../libs/shared/src/lib/models/src/numbered.invoice.model.ts"],"names":[],"mappings":"AA0BA,MAAM,CAAN,IAAY,oBAsEX;AAtED,WAAY,oBAAoB;IAC/B,+DAAuC,CAAA;IACvC,uDAA+B,CAAA;IAC/B,mDAA2B,CAAA;IAC3B,8DAAsC,CAAA;IACtC,kEAA0C,CAAA;IAC1C,iDAAyB,CAAA;IACzB,qDAA6B,CAAA;IAC7B,6CAAqB,CAAA;IACrB,iDAAyB,CAAA;IACzB,oEAAoE;IACpE,0EAA0E;IAC1E,yEAAyE;IACzE,+DAAuC,CAAA;IACvC,oDAA4B,CAAA;IAC5B,wDAAgC,CAAA;IAChC,2DAAmC,CAAA;IACnC,+DAAuC,CAAA;IACvC,yCAAiB,CAAA;IACjB,uDAA+B,CAAA;IAC/B,2DAAmC,CAAA;IACnC,uDAA+B,CAAA;IAC/B,2DAAmC,CAAA;IACnC,2DAAmC,CAAA;IACnC,iDAAyB,CAAA;IACzB,iDAAyB,CAAA;IACzB,qDAA6B,CAAA;IAE7B,uDAA+B,CAAA;IAC/B,6DAAqC,CAAA;IAErC,+CAAuB,CAAA;IACvB,uCAAe,CAAA;IAEf,mDAA2B,CAAA;IAC3B,uDAA+B,CAAA;IAE/B,2DAAmC,CAAA;IACnC,+DAAuC,CAAA;IAEvC,yDAAiC,CAAA;IAEjC,0DAAkC,CAAA;IAClC,uDAA+B,CAAA;IAC/B,uDAA+B,CAAA;IAC/B,mDAA2B,CAAA;IAC3B,uDAA+B,CAAA;IAC/B,mCAAW,CAAA;IACX,qDAA6B,CAAA;IAC7B,yDAAiC,CAAA;IACjC,uEAA+C,CAAA;IAC/C,6CAAqB,CAAA;IACrB,+CAAuB,CAAA;IACvB,mDAA2B,CAAA;IAC3B,mDAA2B,CAAA;IAC3B,6CAAqB,CAAA;IACrB,yCAAiB,CAAA;IACjB,6CAAqB,CAAA;IACrB,+CAAuB,CAAA;IACvB,mDAA2B,CAAA;IAC3B,iEAAyC,CAAA;IACzC,qEAA6C,CAAA;IAC7C,gDAAwB,CAAA;IACxB,6CAAqB,CAAA;IACrB,qEAA6C,CAAA;IAC7C,yEAAiD,CAAA;IACjD,yCAAiB,CAAA;IACjB,iDAAyB,CAAA;IACzB,6DAAqC,CAAA;IACrC,iEAAyC,CAAA;AAC1C,CAAC,EAtEW,oBAAoB,KAApB,oBAAoB,QAsE/B"}
+{"version":3,"file":"numbered.invoice.model.js","sourceRoot":"","sources":["../../../../../../../libs/shared/src/lib/models/src/numbered.invoice.model.ts"],"names":[],"mappings":"AA0BA,MAAM,CAAN,IAAY,oBAuEX;AAvED,WAAY,oBAAoB;IAC/B,+DAAuC,CAAA;IACvC,uDAA+B,CAAA;IAC/B,mDAA2B,CAAA;IAC3B,8DAAsC,CAAA;IACtC,kEAA0C,CAAA;IAC1C,iDAAyB,CAAA;IACzB,qDAA6B,CAAA;IAC7B,6CAAqB,CAAA;IACrB,iDAAyB,CAAA;IACzB,oEAAoE;IACpE,0EAA0E;IAC1E,yEAAyE;IACzE,+DAAuC,CAAA;IACvC,oDAA4B,CAAA;IAC5B,wDAAgC,CAAA;IAChC,2DAAmC,CAAA;IACnC,+DAAuC,CAAA;IACvC,yCAAiB,CAAA;IACjB,uDAA+B,CAAA;IAC/B,2DAAmC,CAAA;IACnC,uDAA+B,CAAA;IAC/B,2DAAmC,CAAA;IACnC,2DAAmC,CAAA;IACnC,iDAAyB,CAAA;IACzB,iDAAyB,CAAA;IACzB,qDAA6B,CAAA;IAE7B,uDAA+B,CAAA;IAC/B,6DAAqC,CAAA;IAErC,+CAAuB,CAAA;IACvB,uCAAe,CAAA;IAEf,mDAA2B,CAAA;IAC3B,uDAA+B,CAAA;IAE/B,2DAAmC,CAAA;IACnC,+DAAuC,CAAA;IAEvC,yDAAiC,CAAA;IAEjC,0DAAkC,CAAA;IAClC,uDAA+B,CAAA;IAC/B,uDAA+B,CAAA;IAC/B,mDAA2B,CAAA;IAC3B,uDAA+B,CAAA;IAC/B,mCAAW,CAAA;IACX,qDAA6B,CAAA;IAC7B,yDAAiC,CAAA;IACjC,uEAA+C,CAAA;IAC/C,6CAAqB,CAAA;IACrB,+CAAuB,CAAA;IACvB,mDAA2B,CAAA;IAC3B,mDAA2B,CAAA;IAC3B,6CAAqB,CAAA;IACrB,yCAAiB,CAAA;IACjB,6CAAqB,CAAA;IACrB,+CAAuB,CAAA;IACvB,mDAA2B,CAAA;IAC3B,iEAAyC,CAAA;IACzC,qEAA6C,CAAA;IAC7C,gDAAwB,CAAA;IACxB,6CAAqB,CAAA;IACrB,qEAA6C,CAAA;IAC7C,yEAAiD,CAAA;IACjD,yCAAiB,CAAA;IACjB,iDAAyB,CAAA;IACzB,0DAAkC,CAAA;IAClC,6DAAqC,CAAA;IACrC,iEAAyC,CAAA;AAC1C,CAAC,EAvEW,oBAAoB,KAApB,oBAAoB,QAuE/B"}

package/src/lib/utilities/src/ba.contract.extension.code.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Allocating the contract code for an EXTENDED BA contract — AD-3416.
+ *
+ * A BA contract's base code comes from a per-context `SeqMetadata` counter,
+ * read and incremented under a `pessimistic_write` lock
+ * (create.ba.contract.controller.ts). Every base code in a context is
+ * therefore distinct, and distinct even under concurrent creates.
+ *
+ * Extending a contract did not go anywhere near that. It derived the new code
+ * from the old one by string arithmetic alone — `1065` -> `1065E1`,
+ * `1065E1` -> `1065E2` — with no idea what already existed. And the block
+ * that would have retired the extended contract's parent is commented out in
+ * extend.ba.contract.ts, so the parent stays extendable: extend `1065`, let
+ * `1065E1` be surrendered or cancelled, extend `1065` again, and the second
+ * extension is minted as `1065E1` as well. Two distinct contract rows, one
+ * code.
+ *
+ * That matters because the BA Payout template emits one row per contract row
+ * while the upload validator, the payout calculator and the save path all key
+ * contracts by CODE. Both rows then validate against whichever duplicate the
+ * in-memory map kept last, and the application's own unedited template is
+ * rejected on upload (AD-3416; first reported as ISSUE-4 on AD-3288). On
+ * staging this had happened ten times, most recently on 25/09/2026, where
+ * extending `1073` twice produced two `1073E1` rows ninety seconds apart.
+ *
+ * `selectBAPayoutContracts` softens the symptom by collapsing records that
+ * share (BA, code, vehicle) to the most recently edited one, but that is a
+ * read-side tie-break for records keyed in twice, not a fix: applied to two
+ * genuinely different contracts it silently drops one of them from the
+ * payout. The ambiguity has to be prevented where it is created.
+ *
+ * So this module answers the allocation question instead of guessing it:
+ * given the code being extended and the codes already in use, what is the
+ * first extension suffix nobody has taken? The caller supplies the in-use set
+ * — everything in the same business context, which is the scope base codes
+ * are numbered in (on staging, no code is shared by two BAs inside one
+ * context) — and holds a lock while it does, so two simultaneous extensions
+ * cannot both read the same set.
+ */
+/** `1065E2` -> base `1065`, extension 2. A code with no suffix is extension 0. */
+export interface BAContractCodeParts {
+    base: string;
+    extension: number;
+}
+/**
+ * Split a contract code into the part that identifies the contract family and
+ * the extension number.
+ *
+ * The pattern is the one the old generator used, kept deliberately: `(.+)E(\d+)`
+ * anchored at the end. Base codes are plain integers from the sequence
+ * counter, so the only `E` in a well-formed code is the extension marker.
+ */
+export declare function splitBAContractCode(code: unknown): BAContractCodeParts;
+/**
+ * The first extension code of `oldContractCode` that is not already in use.
+ *
+ * `usedCodes` is every contract code already allocated in the scope the
+ * caller is protecting — for extend.ba.contract.ts, every code in the
+ * business context, whatever its status. Cancelled and Surrendered rows are
+ * deliberately included: their codes are still printed on payout statements,
+ * still stored on `BAPayoutRow.contractNo`, and still what the upload
+ * validator looks up, so reusing one recreates exactly the ambiguity this
+ * exists to stop.
+ *
+ * Codes are compared after `normalizeBAContractCode` (trim + upper), the same
+ * normalization `resolveBAPayoutContract` uses to decide that an uploaded row
+ * names a given contract. The two answers cannot disagree.
+ *
+ * Note that this does NOT guarantee the returned suffix is the old one plus
+ * one. Extending `1065` when `1065E1` is taken yields `1065E2`, which is the
+ * point: the code names a row, not a position in a chain, and nothing in the
+ * codebase parses it to find a parent (the parent is a foreign key).
+ */
+export declare function nextExtendedContractCode(oldContractCode: unknown, usedCodes: Iterable<unknown> | null | undefined): string;

package/src/lib/utilities/src/ba.contract.extension.code.js

@@ -0,0 +1,69 @@
+import { normalizeBAContractCode } from './ba.payout.contract.selection';
+/**
+ * Split a contract code into the part that identifies the contract family and
+ * the extension number.
+ *
+ * The pattern is the one the old generator used, kept deliberately: `(.+)E(\d+)`
+ * anchored at the end. Base codes are plain integers from the sequence
+ * counter, so the only `E` in a well-formed code is the extension marker.
+ */
+export function splitBAContractCode(code) {
+    const normalized = normalizeBAContractCode(code);
+    const match = normalized.match(/^(.+)E(\d+)$/);
+    if (!match)
+        return { base: normalized, extension: 0 };
+    const extension = parseInt(match[2], 10);
+    // `E0`, or a suffix so long it does not survive parseInt, is not something
+    // this codebase mints; treat the whole string as the family rather than
+    // inventing an extension number from it.
+    if (!Number.isFinite(extension) || extension < 1) {
+        return { base: normalized, extension: 0 };
+    }
+    return { base: match[1], extension };
+}
+/**
+ * How far the walk will go before giving up. A context would need this many
+ * extensions of one contract to reach it; hitting it means the in-use set is
+ * wrong, and an error naming the code is far more useful than a silent
+ * duplicate or a hung request.
+ */
+const MAX_EXTENSION_SEARCH = 1000;
+/**
+ * The first extension code of `oldContractCode` that is not already in use.
+ *
+ * `usedCodes` is every contract code already allocated in the scope the
+ * caller is protecting — for extend.ba.contract.ts, every code in the
+ * business context, whatever its status. Cancelled and Surrendered rows are
+ * deliberately included: their codes are still printed on payout statements,
+ * still stored on `BAPayoutRow.contractNo`, and still what the upload
+ * validator looks up, so reusing one recreates exactly the ambiguity this
+ * exists to stop.
+ *
+ * Codes are compared after `normalizeBAContractCode` (trim + upper), the same
+ * normalization `resolveBAPayoutContract` uses to decide that an uploaded row
+ * names a given contract. The two answers cannot disagree.
+ *
+ * Note that this does NOT guarantee the returned suffix is the old one plus
+ * one. Extending `1065` when `1065E1` is taken yields `1065E2`, which is the
+ * point: the code names a row, not a position in a chain, and nothing in the
+ * codebase parses it to find a parent (the parent is a foreign key).
+ */
+export function nextExtendedContractCode(oldContractCode, usedCodes) {
+    const { base, extension } = splitBAContractCode(oldContractCode);
+    if (!base) {
+        throw new Error('Cannot allocate an extended contract code: the contract being extended has no code');
+    }
+    const taken = new Set();
+    for (const code of usedCodes || []) {
+        const normalized = normalizeBAContractCode(code);
+        if (normalized)
+            taken.add(normalized);
+    }
+    for (let next = extension + 1; next <= extension + MAX_EXTENSION_SEARCH; next++) {
+        const candidate = `${base}E${next}`;
+        if (!taken.has(candidate))
+            return candidate;
+    }
+    throw new Error(`Cannot allocate an extended contract code for ${base}: ${MAX_EXTENSION_SEARCH} consecutive suffixes from E${extension + 1} are already in use`);
+}
+//# sourceMappingURL=ba.contract.extension.code.js.map

package/src/lib/utilities/src/ba.contract.extension.code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ba.contract.extension.code.js","sourceRoot":"","sources":["../../../../../../../libs/shared/src/lib/utilities/src/ba.contract.extension.code.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAgDzE;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAa;IAChD,MAAM,UAAU,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAC/C,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IAEtD,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACzC,2EAA2E;IAC3E,wEAAwE;IACxE,yCAAyC;IACzC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IAC3C,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;AACtC,CAAC;AAED;;;;;GAKG;AACH,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAElC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,wBAAwB,CACvC,eAAwB,EACxB,SAA+C;IAE/C,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,mBAAmB,CAAC,eAAe,CAAC,CAAC;IACjE,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACd,oFAAoF,CACpF,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,IAAI,IAAI,SAAS,IAAI,EAAE,EAAE,CAAC;QACpC,MAAM,UAAU,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,UAAU;YAAE,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACvC,CAAC;IAED,KACC,IAAI,IAAI,GAAG,SAAS,GAAG,CAAC,EACxB,IAAI,IAAI,SAAS,GAAG,oBAAoB,EACxC,IAAI,EAAE,EACL,CAAC;QACF,MAAM,SAAS,GAAG,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;QACpC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;IAC7C,CAAC;IAED,MAAM,IAAI,KAAK,CACd,iDAAiD,IAAI,KAAK,oBAAoB,+BAA+B,SAAS,GAAG,CAAC,qBAAqB,CAC/I,CAAC;AACH,CAAC"}

package/src/lib/utilities/src/ba.contract.rm.refund.d.ts

@@ -0,0 +1,59 @@
+import { IBAContractPaidRM } from '../../models/src/index';
+/**
+ * An RM refund cannot exceed the retention money that was collected — AD-3098
+ * QA re-open.
+ *
+ * QA set RM Status = Refunded with a refund of 10,000 on a contract that had
+ * collected 5,000, and it saved with no complaint. There was no rule anywhere:
+ * not on the form, not in the DTO, not in the controllers. The RM schedule
+ * then did the only arithmetic it can — Final = previous + Addition − Deletion
+ * — and carried −5,000 from April 2026 through to March 2027, plus the same
+ * for two other contracts (1068: 16,800 refunded against nothing collected;
+ * 1073E1: 300 against nothing collected).
+ *
+ * A negative retention balance is not a state the business has: retention
+ * money is collected before it can be given back. So the guard belongs where
+ * the number is written, not where it is displayed. The report is deliberately
+ * left honest — it keeps showing what the data says, because a report that
+ * quietly clamps a negative balance to zero hides the bad row instead of
+ * surfacing it.
+ */
+/** The two RM/SD statuses that mean "a refund has actually happened". */
+export declare const BA_CONTRACT_REFUND_OPEN_STATUSES: readonly string[];
+/**
+ * Whether a refund on an RM or SD section has actually happened.
+ *
+ * Each section is gated by its OWN status — RM by rvStatus, SD by sdStatus,
+ * never one by the other. A refund date and amount left behind by a status
+ * that has since been set back to Active would otherwise read as a refund that
+ * never occurred. The RM and SD schedules and the legacy SD export all apply
+ * this same gate, which is why it lives here and not beside one of them.
+ */
+export declare const isBAContractRefundOpen: (status: string | null | undefined) => boolean;
+/**
+ * The retention money a contract has actually collected: its non-cancelled
+ * BAContractPaidRM rows, summed.
+ *
+ * `amount` is a `decimal` column, which node-postgres hands back as a STRING.
+ * Adding those without Number() concatenates — 5000 + 5000 becomes "50005000"
+ * — so every value goes through Number() here, once. `ExtendBAContract`'s own
+ * private copy of this reduce does not, which is why callers should use this.
+ */
+export declare function sumNonCancelledPaidRM(rows: IBAContractPaidRM[] | null | undefined): number;
+/**
+ * The refund actually being recorded, or 0 when the status says none is.
+ *
+ * Mirrors what the controllers persist and what the RM schedule deducts, so
+ * the guard cannot reject a value the report would have ignored, or pass one
+ * it would have subtracted.
+ */
+export declare function effectiveRMRefundAmount(rvStatus: string | null | undefined, rvAmount: number | string | null | undefined): number;
+/**
+ * `null` when the refund is within the collected RM, otherwise the message to
+ * return to the caller.
+ *
+ * Zero collected RM means zero available, so any positive refund is rejected —
+ * that is the 1068 case (16,800 refunded against nothing collected) and it is
+ * deliberate, not an edge case that slipped through.
+ */
+export declare function checkRMRefundWithinCollected(rvStatus: string | null | undefined, rvAmount: number | string | null | undefined, collected: number): string | null;

package/src/lib/utilities/src/ba.contract.rm.refund.js

@@ -0,0 +1,85 @@
+import { BAContractPaidRMField, } from '../../models/src/index';
+/**
+ * An RM refund cannot exceed the retention money that was collected — AD-3098
+ * QA re-open.
+ *
+ * QA set RM Status = Refunded with a refund of 10,000 on a contract that had
+ * collected 5,000, and it saved with no complaint. There was no rule anywhere:
+ * not on the form, not in the DTO, not in the controllers. The RM schedule
+ * then did the only arithmetic it can — Final = previous + Addition − Deletion
+ * — and carried −5,000 from April 2026 through to March 2027, plus the same
+ * for two other contracts (1068: 16,800 refunded against nothing collected;
+ * 1073E1: 300 against nothing collected).
+ *
+ * A negative retention balance is not a state the business has: retention
+ * money is collected before it can be given back. So the guard belongs where
+ * the number is written, not where it is displayed. The report is deliberately
+ * left honest — it keeps showing what the data says, because a report that
+ * quietly clamps a negative balance to zero hides the bad row instead of
+ * surfacing it.
+ */
+/** The two RM/SD statuses that mean "a refund has actually happened". */
+export const BA_CONTRACT_REFUND_OPEN_STATUSES = [
+    'Adjusted in Car Sale',
+    'Refunded',
+];
+/**
+ * Whether a refund on an RM or SD section has actually happened.
+ *
+ * Each section is gated by its OWN status — RM by rvStatus, SD by sdStatus,
+ * never one by the other. A refund date and amount left behind by a status
+ * that has since been set back to Active would otherwise read as a refund that
+ * never occurred. The RM and SD schedules and the legacy SD export all apply
+ * this same gate, which is why it lives here and not beside one of them.
+ */
+export const isBAContractRefundOpen = (status) => BA_CONTRACT_REFUND_OPEN_STATUSES.includes((status ?? '').trim());
+/** Money is compared at paise precision, never at float noise. */
+const round2 = (n) => Math.round(n * 100) / 100;
+/**
+ * The retention money a contract has actually collected: its non-cancelled
+ * BAContractPaidRM rows, summed.
+ *
+ * `amount` is a `decimal` column, which node-postgres hands back as a STRING.
+ * Adding those without Number() concatenates — 5000 + 5000 becomes "50005000"
+ * — so every value goes through Number() here, once. `ExtendBAContract`'s own
+ * private copy of this reduce does not, which is why callers should use this.
+ */
+export function sumNonCancelledPaidRM(rows) {
+    if (!rows?.length)
+        return 0;
+    return round2(rows.reduce((total, row) => row?.[BAContractPaidRMField.Cancelled]
+        ? total
+        : total +
+            (Number(row?.[BAContractPaidRMField.Amount]) || 0), 0));
+}
+/**
+ * The refund actually being recorded, or 0 when the status says none is.
+ *
+ * Mirrors what the controllers persist and what the RM schedule deducts, so
+ * the guard cannot reject a value the report would have ignored, or pass one
+ * it would have subtracted.
+ */
+export function effectiveRMRefundAmount(rvStatus, rvAmount) {
+    if (!isBAContractRefundOpen(rvStatus))
+        return 0;
+    const amount = Number(rvAmount);
+    return Number.isFinite(amount) && amount > 0 ? round2(amount) : 0;
+}
+/**
+ * `null` when the refund is within the collected RM, otherwise the message to
+ * return to the caller.
+ *
+ * Zero collected RM means zero available, so any positive refund is rejected —
+ * that is the 1068 case (16,800 refunded against nothing collected) and it is
+ * deliberate, not an edge case that slipped through.
+ */
+export function checkRMRefundWithinCollected(rvStatus, rvAmount, collected) {
+    const refund = effectiveRMRefundAmount(rvStatus, rvAmount);
+    if (refund === 0)
+        return null;
+    const available = round2(Number.isFinite(collected) ? collected : 0);
+    if (refund <= available)
+        return null;
+    return `RM Refund Amount (${refund}) cannot exceed the RM collected (${available}).`;
+}
+//# sourceMappingURL=ba.contract.rm.refund.js.map

package/src/lib/utilities/src/ba.contract.rm.refund.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ba.contract.rm.refund.js","sourceRoot":"","sources":["../../../../../../../libs/shared/src/lib/utilities/src/ba.contract.rm.refund.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,qBAAqB,GAErB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;GAkBG;AAEH,yEAAyE;AACzE,MAAM,CAAC,MAAM,gCAAgC,GAAsB;IAClE,sBAAsB;IACtB,UAAU;CACV,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACrC,MAAiC,EACvB,EAAE,CAAC,gCAAgC,CAAC,QAAQ,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAE/E,kEAAkE;AAClE,MAAM,MAAM,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AAEhE;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CACpC,IAA4C;IAE5C,IAAI,CAAC,IAAI,EAAE,MAAM;QAAE,OAAO,CAAC,CAAC;IAC5B,OAAO,MAAM,CACZ,IAAI,CAAC,MAAM,CACV,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,CACd,GAAG,EAAE,CAAC,qBAAqB,CAAC,SAAS,CAAC;QACrC,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,KAAK;YACN,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,EACrD,CAAC,CACD,CACD,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACtC,QAAmC,EACnC,QAA4C;IAE5C,IAAI,CAAC,sBAAsB,CAAC,QAAQ,CAAC;QAAE,OAAO,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChC,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,4BAA4B,CAC3C,QAAmC,EACnC,QAA4C,EAC5C,SAAiB;IAEjB,MAAM,MAAM,GAAG,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC3D,IAAI,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE9B,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrE,IAAI,MAAM,IAAI,SAAS;QAAE,OAAO,IAAI,CAAC;IAErC,OAAO,qBAAqB,MAAM,qCAAqC,SAAS,IAAI,CAAC;AACtF,CAAC"}

package/src/lib/utilities/src/ba.payout.contract.selection.d.ts

@@ -0,0 +1,79 @@
+import { IBAContract } from '../../models/src/index';
+/**
+ * Which BA contract a BA Payout row belongs to — AD-3098 QA re-open.
+ *
+ * The BA Payout template and the upload validator disagreed about contracts,
+ * and the disagreement made a whole month's payout unuploadable:
+ *
+ *  • The template emitted one row per contract overlapping the period with no
+ *    status filter at all, so a Cancelled contract got a row.
+ *  • The validator hashed contracts into `Map<contractCode, contract>` —
+ *    last write wins. `baContractCode` is NOT unique: an older extend flow
+ *    minted duplicate `E<n>` codes (AD-3227, AD-3097), and a contract that is
+ *    cancelled and re-raised keeps its code. On staging, `1004E1` exists twice
+ *    for BA1002 — one Cancelled, one Surrendered — so the validator compared
+ *    the template's Cancelled row against the Surrendered record and reported
+ *    "Contract Start Date mismatch. Expected: 01/12/2025, Found: 02/05/2026".
+ *    Nothing the user could type would satisfy it.
+ *
+ * The rule here is the single answer both sides now use, so they cannot drift:
+ *
+ *  1. Cancelled contracts are not payable and are dropped outright. This is
+ *     the same predicate `loadReportContracts` applies to the RM and SD
+ *     schedules and `findBAContractForBooking` applies to bookings, so the
+ *     payout, the schedules and the booking attribution agree about which
+ *     contracts exist.
+ *  2. The same contract keyed in twice — same BA, same code, same vehicle —
+ *     is ONE contract, collapsed to its most recently edited record. That is
+ *     the tie-break `groupDuplicateContracts` already uses in the report
+ *     builders. Without it the template would print the row twice and the
+ *     payout would collect the RM twice.
+ *  3. The same code on DIFFERENT vehicles stays as separate contracts (BA1000
+ *     has six rows coded '1000' on six vehicles). Those are resolved by the
+ *     vehicle registration carried on the uploaded row, which is the column
+ *     that actually distinguishes them.
+ */
+export declare const normalizeBAContractCode: (raw: unknown) => string;
+/**
+ * Registrations are compared without spaces or punctuation: the template
+ * writes the stored value verbatim, but a user who retypes a cell may enter
+ * "KA 67 BA 105" for a stored "KA67BA105", and a resolution step is the wrong
+ * place to fail over formatting. The "Vehicle mismatch" check downstream still
+ * compares the raw values, so a genuinely different vehicle is still reported.
+ */
+export declare const normalizeVehicleRegistration: (raw: unknown) => string;
+/** A stored timestamp as epoch ms; 0 when it is absent or unparseable. */
+export declare const timestampMs: (value: unknown) => number;
+/**
+ * Most recently edited wins, falling back to most recently created.
+ *
+ * The one definition of "which of these duplicate records is the real one".
+ * `groupDuplicateContracts` in ba.contract.report.shared.ts imports it from
+ * here so the report and the payout resolve a duplicated contract to the SAME
+ * record — two answers to that question is how a sheet and a payout start
+ * disagreeing about money.
+ */
+export declare const isNewerRecord: (candidate: IBAContract, current: IBAContract) => boolean;
+/** A Cancelled contract is never paid out and never appears in the template. */
+export declare const isBAPayoutEligibleContract: (contract: IBAContract | null | undefined) => boolean;
+/**
+ * Drop Cancelled contracts and collapse duplicate records of the same
+ * contract, keeping the most recently edited one. Input order is preserved so
+ * the template's row order does not change for the ordinary case.
+ *
+ * A row missing any part of the identity key is never merged with anything —
+ * it gets its own slot under its own id, exactly as the report builders do.
+ */
+export declare function selectBAPayoutContracts(contracts: IBAContract[] | undefined | null): IBAContract[];
+/**
+ * Pick the one contract an uploaded payout row refers to.
+ *
+ * `candidates` is every contract sharing the row's Contract ID. The vehicle
+ * registration from the row is what separates same-code contracts on different
+ * vehicles. When the row's vehicle matches none of them the newest is returned
+ * anyway, so the caller reports the real problem ("Vehicle mismatch") rather
+ * than the misleading "Contract ID not found in system".
+ */
+export declare function resolveBAPayoutContract(candidates: IBAContract[] | undefined | null, criteria?: {
+    vehicleRegistration?: unknown;
+}): IBAContract | null;

package/src/lib/utilities/src/ba.payout.contract.selection.js

@@ -0,0 +1,137 @@
+import { BAContractField } from '../../models/src/index';
+import { VehicleAssociationField } from '../../models/src/vehicle.association.model';
+import { BAContractStatus } from '../../enums/src/index';
+/**
+ * Which BA contract a BA Payout row belongs to — AD-3098 QA re-open.
+ *
+ * The BA Payout template and the upload validator disagreed about contracts,
+ * and the disagreement made a whole month's payout unuploadable:
+ *
+ *  • The template emitted one row per contract overlapping the period with no
+ *    status filter at all, so a Cancelled contract got a row.
+ *  • The validator hashed contracts into `Map<contractCode, contract>` —
+ *    last write wins. `baContractCode` is NOT unique: an older extend flow
+ *    minted duplicate `E<n>` codes (AD-3227, AD-3097), and a contract that is
+ *    cancelled and re-raised keeps its code. On staging, `1004E1` exists twice
+ *    for BA1002 — one Cancelled, one Surrendered — so the validator compared
+ *    the template's Cancelled row against the Surrendered record and reported
+ *    "Contract Start Date mismatch. Expected: 01/12/2025, Found: 02/05/2026".
+ *    Nothing the user could type would satisfy it.
+ *
+ * The rule here is the single answer both sides now use, so they cannot drift:
+ *
+ *  1. Cancelled contracts are not payable and are dropped outright. This is
+ *     the same predicate `loadReportContracts` applies to the RM and SD
+ *     schedules and `findBAContractForBooking` applies to bookings, so the
+ *     payout, the schedules and the booking attribution agree about which
+ *     contracts exist.
+ *  2. The same contract keyed in twice — same BA, same code, same vehicle —
+ *     is ONE contract, collapsed to its most recently edited record. That is
+ *     the tie-break `groupDuplicateContracts` already uses in the report
+ *     builders. Without it the template would print the row twice and the
+ *     payout would collect the RM twice.
+ *  3. The same code on DIFFERENT vehicles stays as separate contracts (BA1000
+ *     has six rows coded '1000' on six vehicles). Those are resolved by the
+ *     vehicle registration carried on the uploaded row, which is the column
+ *     that actually distinguishes them.
+ */
+export const normalizeBAContractCode = (raw) => raw == null ? '' : String(raw).trim().toUpperCase();
+/**
+ * Registrations are compared without spaces or punctuation: the template
+ * writes the stored value verbatim, but a user who retypes a cell may enter
+ * "KA 67 BA 105" for a stored "KA67BA105", and a resolution step is the wrong
+ * place to fail over formatting. The "Vehicle mismatch" check downstream still
+ * compares the raw values, so a genuinely different vehicle is still reported.
+ */
+export const normalizeVehicleRegistration = (raw) => raw == null
+    ? ''
+    : String(raw)
+        .toUpperCase()
+        .replace(/[^A-Z0-9]/g, '');
+/** A stored timestamp as epoch ms; 0 when it is absent or unparseable. */
+export const timestampMs = (value) => {
+    if (!value)
+        return 0;
+    const ms = new Date(value).getTime();
+    return Number.isNaN(ms) ? 0 : ms;
+};
+/**
+ * Most recently edited wins, falling back to most recently created.
+ *
+ * The one definition of "which of these duplicate records is the real one".
+ * `groupDuplicateContracts` in ba.contract.report.shared.ts imports it from
+ * here so the report and the payout resolve a duplicated contract to the SAME
+ * record — two answers to that question is how a sheet and a payout start
+ * disagreeing about money.
+ */
+export const isNewerRecord = (candidate, current) => {
+    const updatedDelta = timestampMs(candidate[BAContractField.UpdatedAt]) -
+        timestampMs(current[BAContractField.UpdatedAt]);
+    if (updatedDelta !== 0)
+        return updatedDelta > 0;
+    return (timestampMs(candidate[BAContractField.CreatedAt]) >
+        timestampMs(current[BAContractField.CreatedAt]));
+};
+const registrationOf = (contract) => {
+    const va = contract?.[BAContractField.VehicleAssociation];
+    return normalizeVehicleRegistration(va?.[VehicleAssociationField.Registration]);
+};
+/** A Cancelled contract is never paid out and never appears in the template. */
+export const isBAPayoutEligibleContract = (contract) => !!contract &&
+    contract[BAContractField.Status] !== BAContractStatus.Cancelled;
+/**
+ * Drop Cancelled contracts and collapse duplicate records of the same
+ * contract, keeping the most recently edited one. Input order is preserved so
+ * the template's row order does not change for the ordinary case.
+ *
+ * A row missing any part of the identity key is never merged with anything —
+ * it gets its own slot under its own id, exactly as the report builders do.
+ */
+export function selectBAPayoutContracts(contracts) {
+    if (!contracts?.length)
+        return [];
+    const byKey = new Map();
+    const order = [];
+    for (const contract of contracts) {
+        if (!isBAPayoutEligibleContract(contract))
+            continue;
+        const code = normalizeBAContractCode(contract[BAContractField.BAContractCode]);
+        const baId = contract[BAContractField.BusinessAssociateId] ||
+            contract[BAContractField.BusinessAssociate]?.businessAssociateId;
+        const vaId = contract[BAContractField.VehicleAssociationId];
+        const key = baId && vaId && code
+            ? `${baId}|${code}|${vaId}`
+            : `id:${contract[BAContractField.BAContractId]}`;
+        const existing = byKey.get(key);
+        if (!existing) {
+            byKey.set(key, contract);
+            order.push(key);
+            continue;
+        }
+        if (isNewerRecord(contract, existing))
+            byKey.set(key, contract);
+    }
+    return order.map((key) => byKey.get(key));
+}
+/**
+ * Pick the one contract an uploaded payout row refers to.
+ *
+ * `candidates` is every contract sharing the row's Contract ID. The vehicle
+ * registration from the row is what separates same-code contracts on different
+ * vehicles. When the row's vehicle matches none of them the newest is returned
+ * anyway, so the caller reports the real problem ("Vehicle mismatch") rather
+ * than the misleading "Contract ID not found in system".
+ */
+export function resolveBAPayoutContract(candidates, criteria) {
+    const eligible = selectBAPayoutContracts(candidates);
+    if (eligible.length === 0)
+        return null;
+    if (eligible.length === 1)
+        return eligible[0];
+    const wanted = normalizeVehicleRegistration(criteria?.vehicleRegistration);
+    const pool = wanted && eligible.some((c) => registrationOf(c) === wanted)
+        ? eligible.filter((c) => registrationOf(c) === wanted)
+        : eligible;
+    return pool.reduce((best, c) => (isNewerRecord(c, best) ? c : best));
+}
+//# sourceMappingURL=ba.payout.contract.selection.js.map