@mj-biz-apps/orders-entities 5.18.0 → 5.20.0

package/dist/ExternalPaymentBehavior.d.ts

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Pure decisions for money that arrives on an external rail (Bill.com), read by
+ * `Orders.PollExternalPayments`. No I/O, no entities — every rule here is a table or a function of
+ * its arguments, so it can be tested exhaustively and read by a finance reviewer.
+ *
+ * THREE RULES THAT ARE DELIBERATE:
+ *
+ *   UNKNOWN STATUS HOLDS. Bill.com's `receivable-payments.status` vocabulary is not in the
+ *   connector's catalog; the table below is what the sandbox showed (spike S2) plus the obvious
+ *   spellings. A status not in the table is HELD and surfaced, never read as cleared — a payment
+ *   recorded on a guess is a ledger entry for money that may not exist.
+ *
+ *   ALL-OR-NOTHING FAN-OUT. One Bill.com payment can settle many invoices. If any of them is not one
+ *   we issued, the WHOLE payment is Unmatched and nothing is captured — a partial capture would
+ *   misstate the payment and hide the unmatched remainder behind a plausible-looking record.
+ *
+ *   MATCHING IS BY INVOICE ID ONLY. Never by amount, never by `OrderHeader.ExternalDocumentNumber`
+ *   (free-form, hand-editable, not unique — golive #146/#148).
+ *
+ * @module @mj-biz-apps/orders-entities
+ */
+export type ExternalPaymentDisposition = 'Captured' | 'Held' | 'Unmatched' | 'Refused' | 'Ignored' | 'Reapplied' | 'ReversalNeeded';
+export type RailPaymentClass = 'Cleared' | 'Pending' | 'Reversed';
+/**
+ * Bill.com `receivable-payments.status` → what it means for cash. Keys are upper-cased.
+ *
+ * THIS IS THE WHOLE ENUM, not a guess: BILL documents exactly six values for
+ * `ReceivablePaymentResponseDto.status`, and `PAID` on an offline check was confirmed live in the
+ * sandbox on 2026-09-22 (spike S2). An earlier provisional table carried `CLEARED`, `PROCESSING`,
+ * `PENDING`, `VOIDED`, `CANCELLED`, `SETTLED`, `COMPLETED`, `IN_PROCESS`, `FAILED` and `RETURNED` —
+ * none of which BILL can emit. They are gone rather than kept "just in case", because a key that
+ * cannot occur is a claim about the vendor that no one can check.
+ *
+ * `UNDEFINED` is deliberately absent so it falls to `Unknown` → Hold: BILL saying it does not know
+ * is not a reason for us to decide.
+ *
+ * `ESCHEATED` means the funds went unclaimed and were remitted to the state. The money is not coming,
+ * so it classes with the reversals: never captured, and if we already captured it, surfaced as
+ * `ReversalNeeded` for a person.
+ */
+export declare const BILLCOM_PAYMENT_STATUS: Readonly<Record<string, RailPaymentClass>>;
+export declare function ClassifyPaymentStatus(status: string | null | undefined): RailPaymentClass | 'Unknown';
+export interface PaymentSeen {
+    ExternalPaymentRef: string;
+    Status: string | null;
+    /**
+     * True when the rail's current `invoicePayments[]` no longer match the payment lines we hold for
+     * this payment; false when they do. Computed by the caller, which needs the ledger.
+     *
+     * `undefined` means COULD NOT TELL — not checked, or the read behind the comparison failed. It is
+     * deliberately distinct from `false`: on a payment already flagged `Reapplied`, treating "could not
+     * tell" as "no difference" would retire a live exception on one bad database read, with the wrong
+     * allocation still in place.
+     */
+    ApplicationsChanged?: boolean;
+    /** What the last pass did with this payment, or null when it has never been seen. */
+    PriorDisposition: ExternalPaymentDisposition | null;
+}
+export type ExternalPaymentAction = 'Capture' | 'Hold' | 'Ignore' | 'Reapplied' | 'ReversalNeeded';
+export interface ExternalPaymentDecision {
+    Action: ExternalPaymentAction;
+    Reason: string;
+    /**
+     * What the `ExternalPayment` row should now READ AS, when that differs from keeping what it says.
+     *
+     * `Action` is what to do; this is what to store, and the two part company in exactly one place: a
+     * payment flagged `Reapplied` whose allocation has since been corrected needs no action but must
+     * stop reading as an exception. Without it the poller's `Ignore` branch wrote the prior
+     * disposition straight back, so the row sat on the queue page for ever, labelled an exception with
+     * a reason saying there was nothing wrong.
+     */
+    Disposition?: ExternalPaymentDisposition;
+    /**
+     * True when this answer rests on a comparison that could not be made, so the reason already on the
+     * row — which described a difference somebody can act on — is worth more than this one.
+     */
+    KeepPriorReason?: boolean;
+}
+export declare function DecideExternalPayment(p: PaymentSeen): ExternalPaymentDecision;
+/** What the poller needs to know about the unit behind one of our external invoices. */
+export interface UnitRef {
+    OrderHeaderID: string;
+    CompanyID: string;
+    OrderHeaderPaymentScheduleID: string | null;
+    BillToOrganizationID: string | null;
+    BillToPersonID: string | null;
+}
+export interface InvoiceAllocation {
+    OrderHeaderID: string;
+    Amount: number;
+    OrderHeaderPaymentScheduleID: string | null;
+}
+export type AllocationOutcome = {
+    OK: true;
+    Allocations: InvoiceAllocation[];
+    Payer: {
+        BillToOrganizationID: string | null;
+        BillToPersonID: string | null;
+    };
+    CompanyID: string;
+    Total: number;
+} | {
+    OK: false;
+    Unmatched: string[];
+    Reason: string;
+};
+/**
+ * Turn Bill.com's `invoicePayments[]` into `Orders.CapturePayment` allocations, or explain why not.
+ * The lookup answers "which unit did we issue this invoice for" from `ExternalInvoice`.
+ */
+export declare function AllocateInvoicePayments(invoicePayments: ReadonlyArray<{
+    ExternalInvoiceRef: string;
+    Amount: number;
+}>, lookup: (externalInvoiceRef: string) => UnitRef | undefined): AllocationOutcome;
+/** `PaymentHeader.IdempotencyKey` for a rail payment — the D19 guard, enforced by UX_PaymentHeader_IdempotencyKey. */
+export declare function ExternalPaymentIdempotencyKey(typeCode: string, externalPaymentRef: string): string;
+/** The `PaymentType.Code` values this rail can produce. All seeded and active in `metadata/payment-types`. */
+export type OrdersTenderCode = 'ACH' | 'Cash' | 'Check' | 'CreditCard' | 'Wire';
+export declare function TenderFor(p: {
+    OnlinePayment: boolean | null;
+    ReceivablesType: string | null;
+}): OrdersTenderCode;
+//# sourceMappingURL=ExternalPaymentBehavior.d.ts.map

package/dist/ExternalPaymentBehavior.d.ts.map

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

package/dist/ExternalPaymentBehavior.js

@@ -0,0 +1,217 @@
+/**
+ * @fileoverview Pure decisions for money that arrives on an external rail (Bill.com), read by
+ * `Orders.PollExternalPayments`. No I/O, no entities — every rule here is a table or a function of
+ * its arguments, so it can be tested exhaustively and read by a finance reviewer.
+ *
+ * THREE RULES THAT ARE DELIBERATE:
+ *
+ *   UNKNOWN STATUS HOLDS. Bill.com's `receivable-payments.status` vocabulary is not in the
+ *   connector's catalog; the table below is what the sandbox showed (spike S2) plus the obvious
+ *   spellings. A status not in the table is HELD and surfaced, never read as cleared — a payment
+ *   recorded on a guess is a ledger entry for money that may not exist.
+ *
+ *   ALL-OR-NOTHING FAN-OUT. One Bill.com payment can settle many invoices. If any of them is not one
+ *   we issued, the WHOLE payment is Unmatched and nothing is captured — a partial capture would
+ *   misstate the payment and hide the unmatched remainder behind a plausible-looking record.
+ *
+ *   MATCHING IS BY INVOICE ID ONLY. Never by amount, never by `OrderHeader.ExternalDocumentNumber`
+ *   (free-form, hand-editable, not unique — golive #146/#148).
+ *
+ * @module @mj-biz-apps/orders-entities
+ */
+/**
+ * Bill.com `receivable-payments.status` → what it means for cash. Keys are upper-cased.
+ *
+ * THIS IS THE WHOLE ENUM, not a guess: BILL documents exactly six values for
+ * `ReceivablePaymentResponseDto.status`, and `PAID` on an offline check was confirmed live in the
+ * sandbox on 2026-09-22 (spike S2). An earlier provisional table carried `CLEARED`, `PROCESSING`,
+ * `PENDING`, `VOIDED`, `CANCELLED`, `SETTLED`, `COMPLETED`, `IN_PROCESS`, `FAILED` and `RETURNED` —
+ * none of which BILL can emit. They are gone rather than kept "just in case", because a key that
+ * cannot occur is a claim about the vendor that no one can check.
+ *
+ * `UNDEFINED` is deliberately absent so it falls to `Unknown` → Hold: BILL saying it does not know
+ * is not a reason for us to decide.
+ *
+ * `ESCHEATED` means the funds went unclaimed and were remitted to the state. The money is not coming,
+ * so it classes with the reversals: never captured, and if we already captured it, surfaced as
+ * `ReversalNeeded` for a person.
+ */
+export const BILLCOM_PAYMENT_STATUS = Object.freeze({
+    PAID: 'Cleared',
+    SCHEDULED: 'Pending',
+    VOID: 'Reversed',
+    CANCELED: 'Reversed',
+    ESCHEATED: 'Reversed',
+});
+export function ClassifyPaymentStatus(status) {
+    if (!status)
+        return 'Unknown';
+    return BILLCOM_PAYMENT_STATUS[status.trim().toUpperCase()] ?? 'Unknown';
+}
+export function DecideExternalPayment(p) {
+    const cls = ClassifyPaymentStatus(p.Status);
+    const ref = p.ExternalPaymentRef;
+    // A CAPTURED PAYMENT AND A RE-APPLIED ONE ARE THE SAME QUESTION, asked a poll apart. Both have
+    // cash recorded against them, so both are re-examined the same way — and `Reapplied` is NOT a
+    // terminal disposition (it is deliberately absent from the poller's FINAL set, so every pass
+    // re-decides it). Falling through to the status switch, as this used to, answered `Capture` for a
+    // cleared payment: the capture returned `WasRetry` on the idempotency key, the poller wrote
+    // `Captured` back over the row, and the exception a person was supposed to act on vanished an
+    // hour after it was raised — leaving the wrong allocation in place with nothing flagging it.
+    if (p.PriorDisposition === 'Captured' || p.PriorDisposition === 'Reapplied') {
+        if (cls === 'Reversed') {
+            return { Action: 'ReversalNeeded', Reason: `${ref} was captured and Bill.com now reports it '${p.Status}'. The cash has to be reversed (bank-return path, O-US13); nothing is changed automatically.` };
+        }
+        // THE RAIL CAN MOVE MONEY WE ALREADY RECORDED. Bill.com lets Finance re-apply a receipt:
+        // 700.00 recorded against invoice A last week becomes 300.00 on A and 400.00 on B today, or
+        // moves to invoice C entirely. The payment is unchanged in total, so nothing here is wrong —
+        // but our PaymentLines now point at the wrong invoices, Orders shows B open while Bill.com
+        // shows it paid, and no amount of re-polling notices because the payment is "already
+        // captured". Reported for a person rather than silently ignored, the same posture a void
+        // after capture takes.
+        const alreadyFlagged = p.PriorDisposition === 'Reapplied';
+        if (p.ApplicationsChanged === true) {
+            return {
+                Action: 'Reapplied',
+                Reason: alreadyFlagged
+                    ? `${ref} is still applied differently on Bill.com from the payment lines held here; the allocation has not been corrected.`
+                    : `${ref} was captured, and Bill.com has since applied it to different invoices. The cash is right; the allocation here is not. Re-allocate it by hand — nothing is changed automatically.`,
+            };
+        }
+        // COULD NOT TELL is not ALL CLEAR. `undefined` means the comparison was not made, or the read
+        // behind it failed. On a row already flagged that must hold the flag AND the words on it: they
+        // describe a real difference somebody can act on, and one bad database read must not retire it.
+        // A merely captured row is unaffected — there is nothing to hold.
+        if (alreadyFlagged && p.ApplicationsChanged === undefined) {
+            return {
+                Action: 'Reapplied',
+                Reason: `${ref} is flagged re-applied and the applications could not be compared on this pass; the flag stands until they can be.`,
+                KeepPriorReason: true,
+            };
+        }
+        // THE EXCEPTION CLEARS ITSELF once the allocation matches again, so a person who re-allocates
+        // by hand does not also have to come back and retire the flag. Storing `Captured` is the point:
+        // leaving `Reapplied` on the row kept it on the queue page for ever, labelled an exception,
+        // under a reason saying there was nothing wrong.
+        if (alreadyFlagged) {
+            return {
+                Action: 'Ignore',
+                Disposition: 'Captured',
+                Reason: `${ref} was re-applied on Bill.com and the allocation here now matches again; the exception is cleared.`,
+            };
+        }
+        return { Action: 'Ignore', Reason: `${ref} is already captured.` };
+    }
+    if (p.PriorDisposition === 'ReversalNeeded') {
+        return { Action: 'Ignore', Reason: `${ref} is already flagged for reversal.` };
+    }
+    if (p.PriorDisposition === 'Ignored') {
+        // Terminal by a person's hand (an Unmatched or Refused row set to Ignored), or a reversal that
+        // was never captured. Either way, nothing here re-opens it — a status flip on the rail cannot
+        // make pre-cutover AR ours.
+        return { Action: 'Ignore', Reason: `${ref} was set aside (Ignored); nothing is captured for it.` };
+    }
+    switch (cls) {
+        case 'Cleared':
+            return { Action: 'Capture', Reason: `${ref} is '${p.Status}': cleared and not yet captured.` };
+        case 'Pending':
+            return { Action: 'Hold', Reason: `${ref} is '${p.Status}': promised, not yet banked. Held until Bill.com reports it cleared.` };
+        case 'Reversed':
+            return { Action: 'Ignore', Reason: `${ref} is '${p.Status}' and was never captured; there is nothing to reverse.` };
+        default:
+            return {
+                Action: 'Hold',
+                Reason: `${ref} has an unknown Bill.com status '${p.Status ?? '(none)'}'. Held rather than guessed — add the status to BILLCOM_PAYMENT_STATUS once its meaning is confirmed.`,
+            };
+    }
+}
+const money = (n) => Math.round((Number(n) + Number.EPSILON) * 100) / 100;
+/**
+ * Turn Bill.com's `invoicePayments[]` into `Orders.CapturePayment` allocations, or explain why not.
+ * The lookup answers "which unit did we issue this invoice for" from `ExternalInvoice`.
+ */
+export function AllocateInvoicePayments(invoicePayments, lookup) {
+    if (!invoicePayments.length) {
+        return { OK: false, Unmatched: [], Reason: 'The payment is applied to no invoice on Bill.com; there is no order to apply it to here.' };
+    }
+    const unmatched = [];
+    const allocations = [];
+    const companies = new Set();
+    let payer = null;
+    for (const ip of invoicePayments) {
+        const unit = lookup(ip.ExternalInvoiceRef);
+        if (!unit) {
+            unmatched.push(ip.ExternalInvoiceRef);
+            continue;
+        }
+        const amount = money(ip.Amount);
+        if (!(amount > 0)) {
+            return { OK: false, Unmatched: [], Reason: `Invoice ${ip.ExternalInvoiceRef} carries a non-positive share (${ip.Amount}); refusing to allocate it.` };
+        }
+        allocations.push({ OrderHeaderID: unit.OrderHeaderID, Amount: amount, OrderHeaderPaymentScheduleID: unit.OrderHeaderPaymentScheduleID });
+        companies.add(unit.CompanyID.toLowerCase());
+        // Orders may carry BOTH a bill-to organisation and a person (no XOR on OrderHeader); the
+        // capture needs exactly one payer, and the organisation is the customer (D65).
+        payer ??= unit.BillToOrganizationID
+            ? { BillToOrganizationID: unit.BillToOrganizationID, BillToPersonID: null }
+            : { BillToOrganizationID: null, BillToPersonID: unit.BillToPersonID };
+    }
+    if (unmatched.length) {
+        return {
+            OK: false,
+            Unmatched: unmatched,
+            Reason: `Bill.com invoice(s) ${unmatched.join(', ')} were not issued by Orders (pre-cutover AR, or created directly in Bill.com). Nothing captured: a partial capture would misstate the payment.`,
+        };
+    }
+    if (companies.size > 1) {
+        return { OK: false, Unmatched: [], Reason: `The payment settles invoices for ${companies.size} receiving companies; one payment must land in one company's books.` };
+    }
+    const total = money(allocations.reduce((s, a) => s + a.Amount, 0));
+    return { OK: true, Allocations: allocations, Payer: payer, CompanyID: allocations.length ? lookup(invoicePayments[0].ExternalInvoiceRef).CompanyID : '', Total: total };
+}
+/** `PaymentHeader.IdempotencyKey` for a rail payment — the D19 guard, enforced by UX_PaymentHeader_IdempotencyKey. */
+export function ExternalPaymentIdempotencyKey(typeCode, externalPaymentRef) {
+    return `${typeCode.toLowerCase()}:${externalPaymentRef}`;
+}
+/**
+ * Bill.com `receivablesType` → an Orders `PaymentType.Code`, for `Orders.CapturePayment`.
+ *
+ * `receivablesType` is the authoritative signal and is read FIRST. An earlier version short-circuited
+ * on `OnlinePayment === true` and answered ACH, which would have booked an online card payment to the
+ * bank: BILL reports the method on online payments too. `OnlinePayment` now only breaks the tie when
+ * BILL reports no type at all, where "BILL moved it" is the one thing we do know.
+ *
+ * The keys are BILL's whole documented enum. Note what is NOT in it: there is no `WIRE`. `CASH` maps
+ * to Orders' own `Cash` type, which the old default silently booked as ACH.
+ *
+ * `OTHER` MEANS WIRE, BY AGREEMENT — not by inference. Wires do arrive (money landing directly in the
+ * bank is marked paid in Bill.com by hand), and BILL has no wire type, so whoever marks the invoice
+ * must pick something from the enum. Jeremy settled this on PR #235 on 2026-09-25, choosing the
+ * convention the spec offered as option A (§13 A): Finance selects `Other` when marking a wire paid,
+ * and `OTHER` maps to Orders' `Wire`. It is safe to spend `OTHER` this way precisely because Finance
+ * confirmed AIDP uses no PayPal, wallet or other tender, so nothing else can legitimately claim it.
+ *
+ * The convention is deliberately NOT a marker read out of the description or reference number: that
+ * would depend on consistent typing by a person, which is exactly what this kind of rule must not do.
+ *
+ * `PAYPAL`, `WALLET` and `UNDEFINED` are left falling to ACH. Finance says they cannot occur, so this
+ * is unreachable rather than a guess — but if one ever did arrive it would book to the bank silently,
+ * which is the same shape of defect the rest of this table exists to remove. Worth revisiting the day
+ * the residue stops being hypothetical; it is not worth inventing a refusal path for today.
+ */
+const BILLCOM_TENDER = Object.freeze({
+    CASH: 'Cash',
+    CHECK: 'Check',
+    CREDIT_CARD: 'CreditCard',
+    VIRTUAL_CARD: 'CreditCard',
+    ACH: 'ACH',
+    // By agreement, not by inference — see above.
+    OTHER: 'Wire',
+});
+export function TenderFor(p) {
+    const mapped = BILLCOM_TENDER[(p.ReceivablesType ?? '').trim().toUpperCase()];
+    if (mapped)
+        return mapped;
+    return 'ACH';
+}
+//# sourceMappingURL=ExternalPaymentBehavior.js.map

package/dist/ExternalPaymentBehavior.js.map

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

package/dist/OrderHeaderEntity.d.ts

@@ -34,6 +34,7 @@ import { mjBizAppsOrdersOrderHeaderEntity } from './generated/entity_subclasses.
 import { type TransitionVerdict } from './OrderStatusBehavior.js';
 import { PromotionCodesCompanion } from './PromotionCodesCompanion.js';
 import { InitialPaymentIntentCompanion } from './InitialPaymentIntentCompanion.js';
+import { type OrderAddressSnapshot } from './order-address-snapshot.js';
 /** The order editor's sections, in the order the screen shows them. */
 export type OrderEditorSection = 'header' | 'parties' | 'lines' | 'charges' | 'payment';
 export declare class OrderHeaderEntity extends mjBizAppsOrdersOrderHeaderEntity {
@@ -58,6 +59,10 @@ export declare class OrderHeaderEntity extends mjBizAppsOrdersOrderHeaderEntity
     ClearInitialPaymentDetail(): void;
     ClearBillToAddress(): void;
     ClearShipToAddress(): void;
+    /** The bill-to address this order was confirmed with, or null before it is confirmed. */
+    get BillToAddressAsSold(): OrderAddressSnapshot | null;
+    /** The ship-to address this order was confirmed with, or null before it is confirmed. */
+    get ShipToAddressAsSold(): OrderAddressSnapshot | null;
     get InitialPaymentReference(): string | null;
     set InitialPaymentReference(value: string | null);
     private isInitialPaymentDetailEmpty;
@@ -139,6 +144,26 @@ export declare class OrderHeaderEntity extends mjBizAppsOrdersOrderHeaderEntity
      * The booking save itself still has to write the figures it just computed.
      */
     private refuseBookedMoneyEdits;
+    /**
+     * Set by the server subclass while it writes the address snapshots itself, so the rule below can
+     * tell its own write from a caller's. Cleared once the save returns.
+     */
+    protected addressSnapshotsStamped: boolean;
+    /**
+     * Refuse a change to where a confirmed order was sold (golive #263).
+     *
+     * A confirmed order keeps the addresses it was sold to for the life of the order: the state a
+     * sale counts in is decided by where the customer was on the date of sale. An address that is
+     * set cannot be replaced or cleared. An empty one may be filled, as an empty bill-to party may
+     * be filled after confirm, and the server snapshots it on that save.
+     * `trg_OrderHeader_AddressFrozenAfterConfirm` (51015) and
+     * `trg_OrderLine_AddressFrozenAfterConfirm` (51016) hold the same rule at the database; this
+     * says so before the round trip, against the field that was changed.
+     *
+     * The snapshots are the server's to write, from the Address rows, so a change to one from
+     * anywhere else is refused on any order.
+     */
+    private refuseBookedAddressEdits;
     /**
      * Which editing SECTION each validation failure belongs to.
      *
@@ -185,8 +210,19 @@ export declare class OrderHeaderEntity extends mjBizAppsOrdersOrderHeaderEntity
      * it asks this, then calls {@link Confirm}.
      */
     ConfirmEligibility(): TransitionVerdict;
-    /** True when {@link Confirm} is a legal next move from what is on this object. */
-    get CanConfirm(): boolean;
+    /**
+     * Lines whose recognition type needs a service period (`RequiresServicePeriod`), that nothing
+     * will date, and that do not have both dates.
+     *
+     * Event lines are left out because the save stamps them from the event, and subscription lines
+     * because it stamps them from the term. What remains has no source but the person entering the
+     * order. The browser asks this before offering Confirm, so the user is told before the server's
+     * recognition driver refuses the booking.
+     *
+     * Reads `OrdersEngine`; the caller loads it. With the cache empty nothing counts, which leaves
+     * the decision to the server.
+     */
+    LinesMissingServicePeriod(): OrderHeaderEntity['Lines']['Items'];
     /**
      * Confirm — the irreversible step.
      *
@@ -199,6 +235,16 @@ export declare class OrderHeaderEntity extends mjBizAppsOrdersOrderHeaderEntity
      * missing payer without a round trip.
      */
     Confirm(): Promise<void>;
+    /**
+     * Move to `status` by saving, and put the previous status back if the save is refused.
+     *
+     * Without the restore a refused transition stays on the object as an unsaved edit: the screen
+     * reads the new status, `IsBookedOrder` hides the verbs that depend on it, and every later save
+     * re-sends the same transition and is refused the same way, whatever else changed.
+     *
+     * Throws with the server's reason.
+     */
+    SaveStatus(status: OrderHeaderEntity['Status'], fallbackMessage: string): Promise<void>;
     /**
      * Load this order and its lines together — the state an editor needs.
      *

package/dist/OrderHeaderEntity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OrderHeaderEntity.d.ts","sourceRoot":"","sources":["../src/OrderHeaderEntity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAwE,gBAAgB,EAAW,KAAK,oBAAoB,EAAyB,MAAM,sBAAsB,CAAC;AAGzL,OAAO,EAAE,gCAAgC,EAAsC,MAAM,+BAA+B,CAAC;AACrH,OAAO,EAA4C,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAEzG,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AAWhF,uEAAuE;AACvE,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAKxF,qBACa,iBAAkB,SAAQ,gCAAgC;IACnE;;OAEG;IACI,YAAY,CAAC,GAAG,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO;IAIrD;;;;;;;OAOG;IACH,SAAgB,cAAc,0BAA6D;IAE3F;;;OAGG;IACH,SAAgB,oBAAoB,gCAAmE;IAEhG,yBAAyB,IAAI,IAAI;IAKjC,kBAAkB,IAAI,IAAI;IAI1B,kBAAkB,IAAI,IAAI;IAIjC,IAAW,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAMlD;IAED,IAAW,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAmBtD;IAED,OAAO,CAAC,2BAA2B;IAanC;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,eAAe,UAAS;IAElC,kFAAkF;IAClF,SAAS,CAAC,kBAAkB,IAAI,OAAO;IAOvC;;;;;;;;;;OAUG;IACH;;;;;;;;;OASG;IACH,SAAS,CAAC,uBAAuB,IAAI,iBAAiB;IAKtD,mGAAmG;IACnG,SAAS,CAAC,uBAAuB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM;IAIrE;;;;;;OAMG;IACa,SAAS,CAAC,SAAS,CAAC,EAAE,oBAAoB,GAAG,OAAO;IAapD,QAAQ,IAAI,gBAAgB;IAiF5C;;;;;;;;;OASG;IACH,OAAO,CAAC,4BAA4B;IAcpC,4DAA4D;IAC5D,IAAW,aAAa,IAAI,OAAO,CAElC;IAED;;;;;OAKG;IACH,IAAW,WAAW,IAAI,OAAO,CAIhC;IAED;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAqD9B;;;;;;;;;;;;;OAaG;WACW,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,kBAAkB;IAuBpF;;;;;OAKG;IACI,kBAAkB,IAAI,kBAAkB,EAAE;IAUjD;;;;;;;;;;;;;;OAcG;IACU,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAMzC;;;;;;OAMG;IACI,kBAAkB,IAAI,iBAAiB;IAe9C,kFAAkF;IAClF,IAAW,UAAU,IAAI,OAAO,CAE/B;IAED;;;;;;;;;;OAUG;IACU,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAUrC;;;;;;;;OAQG;IACU,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOnE;;;;;;;;OAQG;IACU,wBAAwB,CAAC,OAAO,GAAE,QAAQ,GAAG,QAAQ,GAAG,MAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBpG;;;OAGG;IACU,gCAAgC,CACzC,SAAS,GAAE,QAAQ,GAAG,QAAmB,EACzC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GACzB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAwB5B"}
+{"version":3,"file":"OrderHeaderEntity.d.ts","sourceRoot":"","sources":["../src/OrderHeaderEntity.ts"],"names":[],"mappings":"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"}

package/dist/OrderHeaderEntity.js

@@ -44,8 +44,10 @@ import { ResolveActiveEmployerOrganization } from './PartyAffiliationBehavior.js
 import { PromotionCodesCompanion } from './PromotionCodesCompanion.js';
 import { InitialPaymentIntentCompanion } from './InitialPaymentIntentCompanion.js';
 import { IsSavePopulatedFieldError } from './save-populated-fields.js';
+import { OrdersEngine } from './pricing/OrdersEngine.js';
 import { anyFieldIsDirty } from './field-dirty.js';
 import { AsDateValue, TodayAsDateValue } from './date-cell.js';
+import { ParseAddressSnapshot } from './order-address-snapshot.js';
 import { BookedMoneyEditMessage, ORDER_HEADER_MONEY_FIELDS, ORDER_HEADER_SET_ONCE_FIELDS, ORDER_LINE_MONEY_FIELDS, } from './booked-money.js';
 /** Statuses that mean the order has been booked to the ledger (plan D8). */
 const BOOKED_STATUSES = new Set(['Confirmed']);
@@ -84,6 +86,11 @@ let OrderHeaderEntity = OrderHeaderEntity_1 = class OrderHeaderEntity extends mj
          * `protected` because the server subclass sets it around its booking walk.
          */
         this.bookingInFlight = false;
+        /**
+         * Set by the server subclass while it writes the address snapshots itself, so the rule below can
+         * tell its own write from a caller's. Cleared once the save returns.
+         */
+        this.addressSnapshotsStamped = false;
     }
     /**
      * True when any of the named fields has unsaved changes. See {@link anyFieldIsDirty}.
@@ -101,6 +108,14 @@ let OrderHeaderEntity = OrderHeaderEntity_1 = class OrderHeaderEntity extends mj
     ClearShipToAddress() {
         this.GetCompanion('ShipToAddressID_Object')?.Clear();
     }
+    /** The bill-to address this order was confirmed with, or null before it is confirmed. */
+    get BillToAddressAsSold() {
+        return ParseAddressSnapshot(this.BillToAddressSnapshot);
+    }
+    /** The ship-to address this order was confirmed with, or null before it is confirmed. */
+    get ShipToAddressAsSold() {
+        return ParseAddressSnapshot(this.ShipToAddressSnapshot);
+    }
     get InitialPaymentReference() {
         return (this.InitialPaymentDetailID_Object?.ReferenceNumber ??
             this.InitialPaymentIntent.Reference ??
@@ -212,6 +227,7 @@ let OrderHeaderEntity = OrderHeaderEntity_1 = class OrderHeaderEntity extends mj
         const result = super.Validate();
         this.dropSavePopulatedFieldErrors(result);
         this.refuseBookedMoneyEdits(result);
+        this.refuseBookedAddressEdits(result);
         const verdict = this.statusTransitionVerdict();
         if (!verdict.Allowed) {
             result.Success = false;
@@ -330,6 +346,54 @@ let OrderHeaderEntity = OrderHeaderEntity_1 = class OrderHeaderEntity extends mj
         result.Success = false;
         result.Errors.push(new ValidationErrorInfo('Status', message, this.Status, ValidationErrorType.Failure));
     }
+    /**
+     * Refuse a change to where a confirmed order was sold (golive #263).
+     *
+     * A confirmed order keeps the addresses it was sold to for the life of the order: the state a
+     * sale counts in is decided by where the customer was on the date of sale. An address that is
+     * set cannot be replaced or cleared. An empty one may be filled, as an empty bill-to party may
+     * be filled after confirm, and the server snapshots it on that save.
+     * `trg_OrderHeader_AddressFrozenAfterConfirm` (51015) and
+     * `trg_OrderLine_AddressFrozenAfterConfirm` (51016) hold the same rule at the database; this
+     * says so before the round trip, against the field that was changed.
+     *
+     * The snapshots are the server's to write, from the Address rows, so a change to one from
+     * anywhere else is refused on any order.
+     */
+    refuseBookedAddressEdits(result) {
+        const refuse = (source, message) => {
+            result.Success = false;
+            result.Errors.push(new ValidationErrorInfo(source, message, null, ValidationErrorType.Failure));
+        };
+        const wasSet = (entity, name) => entity.GetFieldByName(name)?.OldValue != null;
+        if (!this.addressSnapshotsStamped) {
+            for (const name of ['BillToAddressSnapshot', 'ShipToAddressSnapshot']) {
+                if (this.FieldIsDirty(name)) {
+                    refuse(name, `${name} is written by the server from the Address row and cannot be set directly.`);
+                }
+            }
+            this.Lines.Items.forEach((line, index) => {
+                if (anyFieldIsDirty(line, ['ShipToAddressSnapshot'])) {
+                    refuse(`Lines[${index}].ShipToAddressSnapshot`, 'ShipToAddressSnapshot is written by the server from the Address row and cannot be set directly.');
+                }
+            });
+        }
+        if (!this.MoneyLocked)
+            return;
+        const order = `Order ${this.OrderNumber ?? ''}`.trim();
+        for (const name of ['BillToAddressID', 'ShipToAddressID']) {
+            if (this.FieldIsDirty(name) && wasSet(this, name)) {
+                refuse(name, `${order} is confirmed, so its ${name === 'BillToAddressID' ? 'bill-to' : 'ship-to'} address ` +
+                    `cannot be replaced or cleared: the order keeps the address it was sold to. Use a reversal order.`);
+            }
+        }
+        this.Lines.Items.forEach((line, index) => {
+            if (line.IsSaved && anyFieldIsDirty(line, ['ShipToAddressID']) && wasSet(line, 'ShipToAddressID')) {
+                refuse(`Lines[${index}].ShipToAddressID`, `${order} is confirmed, so line ${line.LineNumber ?? index + 1}'s ship-to address cannot be ` +
+                    `replaced or cleared: the line keeps the address it was sold to. Use a reversal order.`);
+            }
+        });
+    }
     /**
      * Which editing SECTION each validation failure belongs to.
      *
@@ -424,11 +488,33 @@ let OrderHeaderEntity = OrderHeaderEntity_1 = class OrderHeaderEntity extends mj
         if (this.Lines.Count === 0 && (!this.IsSaved || this.Lines.IsLoaded)) {
             return { Allowed: false, Reason: 'Need a line.' };
         }
+        const undated = this.LinesMissingServicePeriod();
+        if (undated.length > 0) {
+            const numbers = undated.map((l) => l.LineNumber).filter((n) => n != null);
+            const which = numbers.length > 0 ? `Line ${numbers.join(', ')}` : 'A line';
+            return {
+                Allowed: false,
+                Reason: `${which} needs a service period (start and end date) before this can be confirmed.`,
+            };
+        }
         return { Allowed: true };
     }
-    /** True when {@link Confirm} is a legal next move from what is on this object. */
-    get CanConfirm() {
-        return this.ConfirmEligibility().Allowed;
+    /**
+     * Lines whose recognition type needs a service period (`RequiresServicePeriod`), that nothing
+     * will date, and that do not have both dates.
+     *
+     * Event lines are left out because the save stamps them from the event, and subscription lines
+     * because it stamps them from the term. What remains has no source but the person entering the
+     * order. The browser asks this before offering Confirm, so the user is told before the server's
+     * recognition driver refuses the booking.
+     *
+     * Reads `OrdersEngine`; the caller loads it. With the cache empty nothing counts, which leaves
+     * the decision to the server.
+     */
+    LinesMissingServicePeriod() {
+        const engine = OrdersEngine.Instance;
+        return this.Lines.Items.filter((line) => !(line.ServicePeriodStart && line.ServicePeriodEnd) &&
+            engine.ServicePeriodSource(line.ProductID) === 'Line');
     }
     /**
      * Confirm — the irreversible step.
@@ -445,9 +531,23 @@ let OrderHeaderEntity = OrderHeaderEntity_1 = class OrderHeaderEntity extends mj
         if (this.IsSaved && !this.Lines.IsLoaded) {
             await this.Lines.Load();
         }
-        this.Status = 'Confirmed';
+        await this.SaveStatus('Confirmed', 'The order could not be confirmed.');
+    }
+    /**
+     * Move to `status` by saving, and put the previous status back if the save is refused.
+     *
+     * Without the restore a refused transition stays on the object as an unsaved edit: the screen
+     * reads the new status, `IsBookedOrder` hides the verbs that depend on it, and every later save
+     * re-sends the same transition and is refused the same way, whatever else changed.
+     *
+     * Throws with the server's reason.
+     */
+    async SaveStatus(status, fallbackMessage) {
+        const previous = this.Status;
+        this.Status = status;
         if (!(await this.Save())) {
-            throw new Error(this.LatestResult?.CompleteMessage?.trim() || 'The order could not be confirmed.');
+            this.Status = previous;
+            throw new Error(this.LatestResult?.CompleteMessage?.trim() || fallbackMessage);
         }
     }
     /**