@peabody-soft/mbs-model-ts 1.5.0 → 1.6.0

package/dist/ProtoMap.js

@@ -62,7 +62,8 @@ import Tax from "./Tax";
 import UserProfile from "./UserProfile";
 import WorkingDays, { WorkingHours, WorkingHoursRange } from "./WorkingDays";
 // #region A response and the blobs it is cached as
-// Every entity of a response, in declaration order (parents before children). A tombstone is included, flagged.
+// Every entity of a response, in declaration order (parents before children). Tombstones are
+// included, flagged.
 export function getBusinessResponseEntities(response) {
     const result = [];
     if (response.business !== undefined)
@@ -85,8 +86,8 @@ export function getBusinessResponseEntities(response) {
         result.push(toItemWireEntity(price.item, proto_Price.toBinary(price)));
     return result;
 }
-// Every entity of a profile sync out response: the caller, their links, and the businesses those links name.
-// The three have separate cursors, so unlike a business response the order between the arrays does not matter.
+// Every entity of a profile response: the caller, their links, and the businesses those name. The
+// three have separate cursors, so unlike a business response the array order does not matter.
 export function getProfileResponseEntities(response) {
     const result = [];
     if (response.user !== undefined)
@@ -97,13 +98,12 @@ export function getProfileResponseEntities(response) {
         result.push(toWireEntity(business.entity, proto_Business.toBinary(business)));
     return result;
 }
-// What a business response is cached as: one blob per live entity, the ids its tombstones named,
-// and the attachment base url in a blob of its own, since it belongs to the business rather than to
-// any entity of it.
+// One blob per entity, tombstones included and as sent, plus the attachment base url in a blob of its
+// own (it belongs to the business, not to an entity).
 export function businessResponseToCacheWrite(response) {
     const write = toCacheWrite(getBusinessResponseEntities(response));
-    // Its eTag is its expiry, which is exactly its cursor: a client sends back the expiry it holds
-    // and is sent a later url only when one exists
+    // Its eTag is its expiry, which is also its cursor: a client sends back the expiry it holds and
+    // gets a later url only if one exists.
     const attachmentBaseUrl = response.attachmentBaseUrl;
     if (attachmentBaseUrl !== undefined)
         write.blobs.push({
@@ -113,36 +113,32 @@ export function businessResponseToCacheWrite(response) {
         });
     return write;
 }
-// The same for a profile response, which carries nothing but entities.
+// The same for a profile response, which holds only entities.
 export function profileResponseToCacheWrite(response) {
     return toCacheWrite(getProfileResponseEntities(response));
 }
-// The expiry of the attachment base url a response carried, and zero when it carried none, which
-// is exactly what the next request sends back.
-// Here rather than at a call site, because reading a field of a response is this file's job.
+// The expiry of the attachment base url a response carried, or zero when none. The next request
+// sends it back.
 export function getBusinessResponseAttachmentBaseUrlExpiry(response) {
     return response?.attachmentBaseUrl?.expiry ?? 0n;
 }
-// One order as its own blob, for a caller holding a message rather than a whole response. The
-// payload is the only thing that says which a message is, so one carrying the other is refused
-// here rather than stored where a read would never find it.
-// heldETag is what the container holds that order at, and null when it holds none - see messageToBlob.
+// One order as its own blob, for a caller holding a message rather than a response. Only the payload
+// says what a message is, so a non-order is refused here instead of stored where a read would not
+// find it. heldETag is the eTag the container holds the order at, or null - see messageToBlob.
 export function orderToBlob(order, heldETag) {
     if (order.payload.oneofKind !== "salesOrder")
         throw new InvalidArgumentException("That message carries no sales order, so it is not an order");
     return messageToBlob(order, heldETag);
 }
-// Whether a message carries party preferences. Here rather than at a call site, because reading a
-// field of a message is this file's job.
+// Whether a message carries party preferences.
 export function isPartyPreferencesMessage(message) {
     return message.payload.oneofKind === "partyPreferences";
 }
-// When a message was last written: the field to compare two copies of one thing on when they are
-// held at different ids, and so have no version to be compared by.
+// When a message was last written. It compares two copies of one thing held at different ids, which
+// have no shared version.
 export function getMessageUpdatedAt(message) {
     return getEntity(message.entity).updatedAt;
 }
-// Here rather than at a call site, because reading a field of a message is this file's job.
 export function getMessageId(message) {
     return getEntity(message.entity).id;
 }
@@ -152,10 +148,9 @@ export function partyPreferencesToBlob(partyPreferences, heldETag) {
         throw new InvalidArgumentException("That message carries no party preferences");
     return messageToBlob(partyPreferences, heldETag);
 }
-// The response the blobs of a business container make up: everything cached for that business, in
-// the shape the call that brought it returned, and null when they hold nothing of it yet.
-// The entity type in each blob id sorts them, so no stored type tag is needed; one this library
-// does not know is skipped rather than refused, so a newer server cannot break an older client.
+// Rebuilds the response a business container's blobs make up, as the call returned it. Null when they
+// hold nothing yet. The entity type in each blob id sorts them, so no type tag is stored. An unknown
+// type is skipped, so a newer server cannot break an older client.
 export function businessResponseFromBlobs(blobs) {
     const response = proto_BusinessSyncOutResponse.create({});
     let hasContent = false;
@@ -202,7 +197,7 @@ export function businessResponseFromBlobs(blobs) {
     }
     return hasContent ? response : null;
 }
-// The same for a profile container, whose three entity types are siblings rather than a hierarchy.
+// The same for a profile container, whose three entity types are siblings.
 export function profileResponseFromBlobs(blobs) {
     const response = proto_ProfileSyncOutResponse.create({});
     let hasContent = false;
@@ -226,28 +221,66 @@ export function profileResponseFromBlobs(blobs) {
     }
     return hasContent ? response : null;
 }
-// The orders a container holds. The payload a message carries is what says whether it is an
-// order or a cart - Message.messageType is not read, because here the payload is typed.
-export function orderMessagesFromBlobs(blobs) {
-    const result = [];
-    for (const message of messagesFromBlobs(blobs))
-        if (message.payload.oneofKind === "salesOrder")
-            result.push(message);
-    return result;
+// The tombstones a business container holds, as a response, each as stored (and so as sent). Null
+// when it holds none. The attachment base url belongs to no entity, so it is left out.
+export function deletedBusinessResponseFromBlobs(blobs) {
+    const held = businessResponseFromBlobs(blobs);
+    if (held === null)
+        return null;
+    const deleted = proto_BusinessSyncOutResponse.create({
+        business: held.business !== undefined && isDeletedEntity(getEntity(held.business.entity))
+            ? held.business
+            : undefined,
+        attachments: held.attachments.filter((attachment) => isDeletedEntity(getEntity(attachment.entity))),
+        configurations: held.configurations.filter((configuration) => isDeletedEntity(getEntity(configuration.entity))),
+        messages: held.messages.filter((message) => isDeletedEntity(getEntity(message.entity))),
+        productCategories: held.productCategories.filter((category) => isDeletedItem(category.item)),
+        products: held.products.filter((product) => isDeletedItem(product.item)),
+        packages: held.packages.filter((pkg) => isDeletedItem(pkg.item)),
+        priceLists: held.priceLists.filter((priceList) => isDeletedItem(priceList.item)),
+        prices: held.prices.filter((price) => isDeletedItem(price.item)),
+    });
+    return businessResponseEntityCount(deleted) === 0 ? null : deleted;
 }
-// The party preferences message among messages already in hand, or null when none of them is
-// one. A customer has one per business, so two means two callers' messages are in one container -
-// the most recently updated then wins for want of anything better: nothing in a message says
-// which caller it was sent to - see THE MESSAGES OF A BUSINESS ARE NOT PUBLIC.
-// Split out of partyPreferencesMessageFromBlobs so a caller already holding a response's messages
-// - such as Model.businessSyncIn folding the anonymous container in - can settle its cart without
-// asking the store for the same blobs again. buildBusiness takes the cart it shows from here too, so
-// that the cart shown, the cart amended and the cart carried over a sign in are always one message.
+// The same for a profile container.
+export function deletedProfileResponseFromBlobs(blobs) {
+    const held = profileResponseFromBlobs(blobs);
+    if (held === null)
+        return null;
+    const deleted = proto_ProfileSyncOutResponse.create({
+        user: held.user !== undefined && isDeletedEntity(getEntity(held.user.entity)) ? held.user : undefined,
+        businessLinks: held.businessLinks.filter((businessLink) => isDeletedEntity(getEntity(businessLink.entity))),
+        businesses: held.businesses.filter((business) => isDeletedEntity(getEntity(business.entity))),
+    });
+    return profileResponseEntityCount(deleted) === 0 ? null : deleted;
+}
+// The open orders a container holds, which the business has not completed. The payload says whether
+// a message is an order or a cart. Message.messageType is not read, since the payload is typed.
+export function orderMessagesFromBlobs(blobs) {
+    return ordersAmong(messagesFromBlobs(blobs, false));
+}
+// The orders the business has completed, by fulfilling or cancelling. The merchant app completes an
+// order by deleting its message, so these are tombstones, but a server sends them whole because a
+// customer is shown the order afterwards. A tombstone with no order (left by an older server that
+// sent only the header) is not one.
+export function deletedOrderMessagesFromBlobs(blobs) {
+    return ordersAmong(messagesFromBlobs(blobs, true));
+}
+function ordersAmong(messages) {
+    return messages.filter((message) => message.payload.oneofKind === "salesOrder");
+}
+// The party preferences message among these messages, or null. A customer has one per business, so
+// two means two callers' messages share a container. The greater update number wins for want of
+// anything better, since nothing in a message says which caller it was sent to. See THE MESSAGES OF
+// A BUSINESS ARE NOT PUBLIC.
+// Split from partyPreferencesMessageFromBlobs so a caller already holding the messages (such as
+// Model.businessSyncIn folding the anonymous container in) need not read the blobs again.
+// buildBusiness uses it too, so the cart shown, amended and carried over a sign in is one message.
 export function partyPreferencesMessageFromMessages(messages) {
     let result = null;
     for (const message of messages) {
         if (isDeletedEntity(getEntity(message.entity)))
-            continue; // A tombstone is not a cart, whatever it carries
+            continue; // A tombstone is not a cart
         if (message.payload.oneofKind !== "partyPreferences")
             continue;
         if (result === null ||
@@ -263,17 +296,17 @@ export function partyPreferencesMessageFromBlobs(blobs) {
 }
 // #endregion
 // #region Requests and credentials
-// The request that asks for everything changed since these cursors, about the business it is given: a bigint
-// is the entity id of the Business, which a caller that has read it before has, and a string is its
-// url friendly businessId, which is all that one reading it for the first time has.
-// attachmentBaseUrlExpiry is not a cursor, just the expiry of the url already held, sent back unchanged (zero when none is held).
+// The request for everything changed since these cursors. A bigint business is the Business entity
+// id, which a caller that has read it before has. A string is its url friendly businessId, which is
+// all a first read has. attachmentBaseUrlExpiry is not a cursor but the expiry of the url already
+// held, sent back unchanged (zero when none).
 export function buildBusinessSyncOutRequest(business, syncInState, attachmentBaseUrlExpiry) {
     return createBusinessSyncOutRequest(typeof business === "bigint"
         ? { oneofKind: "businessEntityId", businessEntityId: business }
         : { oneofKind: "businessId", businessId: business }, syncInState, attachmentBaseUrlExpiry);
 }
-// Takes the business as the request holds it, so that the request after a page can name it exactly as
-// the one before did, whichever way that was
+// Takes the business as the request holds it, so the request after a page names it the same way as
+// the one before.
 function createBusinessSyncOutRequest(business, syncInState, attachmentBaseUrlExpiry) {
     return proto_BusinessSyncOutRequest.create({
         business: business,
@@ -285,11 +318,10 @@ function createBusinessSyncOutRequest(business, syncInState, attachmentBaseUrlEx
         itemUpdateNumber: syncInState.getUpdateNumber(proto_Constants.ITEM_ENTITY_TYPE_ID),
     });
 }
-// How far a container has been read, as the blobs that keep it: one for each key that a page has
-// moved, at an id of its own - see Ids.getSyncCursorBlobId. The cursor is the eTag and there is
-// nothing else to keep, so there are no bytes. A cursor is therefore only ever raised: the store
-// refuses a blob that is not the greater, so a cursor is not lowered by a page that is stale or sent
-// again, nor by another tab that wrote at the same time.
+// How far a container has been read, as one blob per moved key at its own id - see
+// Ids.getSyncCursorBlobId. The cursor is the eTag, so there are no bytes. A cursor only rises: the
+// store refuses a blob that is not greater, so a stale or repeated page, or another tab writing at
+// the same time, cannot lower it.
 export function cursorsToBlobs(cursors, movedKeys) {
     const blobs = [];
     for (const key of movedKeys)
@@ -300,10 +332,10 @@ export function cursorsToBlobs(cursors, movedKeys) {
         });
     return blobs;
 }
-// The cursors a container holds, from the blobs it holds at the cursor ids of keys, in the order of
-// keys and null where it holds none: a state at zero for one that was never read, or was filled by a
-// version that did not keep them, which asks for everything again and is sent it again, a cost in
-// bandwidth and no more: the store keeps a blob only when its eTag is greater.
+// The cursors a container holds, from the blobs at the cursor ids of keys (in key order, null where
+// none). A container never read, or filled by a version that kept no cursors, gets zeros and asks for
+// everything again. That costs bandwidth only, since the store keeps a blob only when its eTag is
+// greater.
 export function cursorsFromBlobs(keys, blobs) {
     const cursors = new SyncState(keys);
     for (const [index, key] of keys.entries()) {
@@ -313,35 +345,31 @@ export function cursorsFromBlobs(keys, blobs) {
     }
     return cursors;
 }
-// Raises these cursors to what a page of a business read brought, tombstones included, and answers
-// the keys that moved. The only thing that moves them: what this client pushed does not.
+// Raises the cursors to what a page of a business read brought, tombstones included, and answers the
+// keys that moved. Only a read moves them. What this client pushed does not.
 export function raiseBusinessCursors(cursors, response) {
     return raiseCursorsFrom(cursors, getBusinessResponseEntities(response));
 }
-// The request that pushes back what this customer has changed. Messages are the only entity type a
-// storefront may push, and one request is one batch: an order and the cart it emptied go together,
-// so that a customer can never be left holding an order and a cart still full of the same items.
-// messageUpdateNumber is how far the reads of this customer's container have got with messages, and
-// not what a push has since stored: the response is this push's own messages, under the update
-// numbers the server assigns them, and nothing else.
+// The request that pushes what this customer changed. A storefront may push only messages, and one
+// request is one batch, so an order and the cart it emptied go together and a customer is never left
+// holding the order and a still full cart. messageUpdateNumber is how far reads of this container
+// have got with messages - see SyncCache.readMessageUpdateNumber.
 export function buildBusinessSyncInRequest(messageUpdateNumber, messages) {
     return proto_BusinessSyncInRequest.create({
         messageUpdateNumber: messageUpdateNumber,
         messages: [...messages],
     });
 }
-// The messages a sync in response carried - this push's own, now bearing the update numbers the
-// server assigned them, and no others. Nothing is to be made of those numbers: they are not how far a read has got.
+// The messages a sync in response carried: this push's own, with the update numbers the server
+// assigned. Those numbers are not how far a read has got.
 export function getSyncInResponseMessages(response) {
     return response.messages;
 }
-// The same, for the profile of the caller - names no business, since a profile sync is not scoped
-// to one and has no sync in.
-// joinBusinessId is the exception, and it is not a scope but an instruction: make the caller a
-// customer of that business, by entity id, while answering. Constants.ENTITY_ID_NULL asks for no
-// join, which is what every ordinary read carries, and it is the default for that reason. A join
-// belongs to one call and not to a read, so nextProfileSyncOutRequest leaves it off the pages that
-// follow - see there.
+// The request for everything changed in the caller's profile since these cursors. It names no
+// business, since a profile sync is not scoped to one and has no sync in. joinBusinessId tells the
+// server to make the caller a customer of that business, by entity id, while answering.
+// Constants.ENTITY_ID_NULL asks for no join and is the default, since an ordinary read joins
+// nothing. A join belongs to one call, so nextProfileSyncOutRequest leaves it off later pages.
 export function buildProfileSyncOutRequest(syncInState, joinBusinessId = BigInt(proto_Constants.ENTITY_ID_NULL)) {
     return proto_ProfileSyncOutRequest.create({
         userUpdateNumber: syncInState.getUpdateNumber(proto_Constants.USER_ENTITY_TYPE_ID),
@@ -354,9 +382,8 @@ export function buildProfileSyncOutRequest(syncInState, joinBusinessId = BigInt(
 export function raiseProfileCursors(cursors, response) {
     return raiseCursorsFrom(cursors, getProfileResponseEntities(response));
 }
-// The user a sign up asks the server to create, as CreateUserRequest.user. Built from the domain
-// object rather than carrying one of its own: this user has no entity yet - the server assigns id,
-// createdAt and updatedAt on creation - so none of EntityHeader goes out here.
+// The user a sign up asks the server to create, as CreateUserRequest.user. It has no entity yet (the
+// server assigns id, createdAt and updatedAt), so none of EntityHeader goes out.
 export function buildUser(userProfile) {
     return proto_User.create({
         firstName: userProfile.firstName,
@@ -366,22 +393,21 @@ export function buildUser(userProfile) {
         preferredLanguageCode: stringToProto(userProfile.preferredLanguageCode),
     });
 }
-// The user Service.updateUser asks the server to overwrite this customer's profile with - the same
-// fields as buildUser, plus the one field that call matches the caller by: its own entity id.
-// Nothing else of EntityHeader goes out, because nothing else of it is read on that call.
+// The user Service.updateUser overwrites this customer's profile with: the fields of buildUser plus
+// the entity id, which the call matches the caller by. The rest of EntityHeader is not read on that
+// call, so it is not sent.
 export function buildUpdateUser(userProfile) {
     return proto_User.create({
         ...buildUser(userProfile),
         entity: proto_Entity.create({ id: userProfile.id }),
     });
 }
-// The two halves of what a join must be answered with, each asked separately so that a caller
-// reporting a server that answered without one can say which was missing - see
-// Model.requireJoinedBusiness. Both take the id rather than the request, because both of the
-// requests that carry a joinBusinessId need them.
-// The membership itself: a live BusinessLink naming that business. A tombstoned one is not a
-// membership - see OBJECT MODEL - so it does not count, and neither does a link to any other
-// business. Its linkToken is the only copy of that credential a profile response carries.
+// The two things a join must be answered with, checked separately so a caller can report which one a
+// server left out - see Model.requireJoinedBusiness. They take the id, since both requests that
+// carry a joinBusinessId need them.
+// The membership itself: a live BusinessLink naming that business. A tombstoned link does not count
+// (see OBJECT MODEL), nor does a link to another business. Its linkToken is the only copy of that
+// credential a profile response carries.
 export function hasJoinedBusinessLink(joinBusinessId, response) {
     if (joinBusinessId === BigInt(proto_Constants.ENTITY_ID_NULL))
         return false;
@@ -391,59 +417,57 @@ export function hasJoinedBusinessLink(joinBusinessId, response) {
             return true;
     return false;
 }
-// The business that link names, matched on Business.entity.id - which is what
-// BusinessLink.businessId is, and not Business.businessId, the url friendly string. A caller needs
-// it as well as the link, because the string is what every later request and container name for
-// that business is built out of, and the link carries only the id.
+// The business the link names, matched on Business.entity.id, which BusinessLink.businessId holds
+// (Business.businessId is the url friendly string). A caller needs the business as well as the link,
+// because every later request and container name is built from that string and the link has only
+// the id.
 export function hasJoinedBusiness(joinBusinessId, response) {
     if (joinBusinessId === BigInt(proto_Constants.ENTITY_ID_NULL))
         return false;
-    // A tombstone of the business is not the business, which is the whole of what a join is answered with it for
+    // A tombstone is not the business, which is what the join is answered with
     for (const business of response.businesses)
         if (getEntity(business.entity).id === joinBusinessId &&
             !isDeletedEntity(getEntity(business.entity)))
             return true;
     return false;
 }
-// The country of the business a response holds, ISO 3166-1 numeric, or undefined when it holds none. A
-// tombstone is not a business and has no country: it is only its header, so the zero it carries must
-// not be taken for one - a cart's taxes are raw codes, which mean something only within a country.
+// The country of the business a response holds, ISO 3166-1 numeric, or undefined when it holds none.
+// A tombstone has no country, and a bare header carries zero, which must not be taken for one: a
+// cart's taxes are raw codes that mean something only within a country.
 export function getBusinessResponseCountryCode(response) {
     const business = response?.business;
     if (business === undefined || isDeletedEntity(getEntity(business.entity)))
         return undefined;
     return business.countryCode;
 }
-// The entity id of the business a response holds, or null when it holds none - which is a response
-// with no business in it, or one with a tombstone, a deleted business being no business to name. Once
-// a business has been read, this is what every later request names it by: its entity id is stable
-// and a url friendly id is only how it was first found.
+// The entity id of the business a response holds, or null when it holds none or only a tombstone.
+// Once a business has been read, later requests name it by this id: it is stable, and the url
+// friendly id is only how it was first found.
 export function getBusinessResponseBusinessEntityId(response) {
     const entity = response?.business?.entity;
     if (entity === undefined || isDeletedEntity(entity))
         return null;
     return entity.id;
 }
-// The url friendly id of the business a response holds - the one that a business is found by, which is not its entity id
-// - or null when it holds none, or only a tombstone, which is only a header and has no business id to tell.
+// The url friendly id of the business a response holds (the one a business is found by, not its
+// entity id), or null when it holds none or only a tombstone.
 export function getBusinessResponseBusinessId(response) {
     const business = response?.business;
     if (business === undefined || isDeletedEntity(getEntity(business.entity)))
         return null;
     return business.businessId;
 }
-// Whether the general settings that a response holds say that the business has turned online shopping on. Settings that
-// are not there - the business has made none, or has deleted them, or this has not read them yet - say that it has not, as
-// settings that say so do. That is what a storefront is told by a business that has not turned it on: the server sends it
-// whatever it says, and a client decides, from what it holds once it has read everything it was sent.
+// Whether the general settings a response holds turn online shopping on. Missing settings (never
+// made, deleted, or not read yet) count as off. The server sends a business's data whether or not
+// shopping is on, so the client decides from what it holds once it has read everything.
 export function isBusinessResponseOnlineShoppingOn(response) {
     if (response === null)
         return false;
     return getGeneralSettingsOf(response)?.onlineShoppingEnabled ?? false;
 }
-// The general settings that a response holds, as the wire carries them, or undefined when it holds none: the one public
-// configuration that carries them, unless it has been deleted, which is only its header. What is read of the settings - the
-// business that is built from them, and whether it is open - is read from here, so that the two cannot be about different ones.
+// The general settings a response holds, as on the wire, or undefined when none: the one public
+// configuration that carries them, unless it is deleted. The business built from them and whether
+// shopping is on both read from here, so they cannot be about different settings.
 function getGeneralSettingsOf(response) {
     let settings;
     for (const configuration of response.configurations) {
@@ -455,8 +479,8 @@ function getGeneralSettingsOf(response) {
     }
     return settings;
 }
-// The credentials of one call, as the wire carries them. An absent token is left off the message
-// rather than sent empty, because the protocol tells the two apart.
+// The credentials of one call, as on the wire. An absent token is left off the message, since the
+// protocol tells absent from empty.
 export function buildAuthTokens(authTokens) {
     const result = proto_AuthTokens.create({
         authenticationMethod: authTokens.authenticationMethod,
@@ -470,21 +494,19 @@ export function buildAuthTokens(authTokens) {
         result.linkToken = linkToken;
     return result;
 }
-// What a server issued while answering a call, in the terms this library holds credentials in
+// What a server issued while answering a call, as this library's AuthTokens
 export function authTokensFromProto(authTokens) {
     return new AuthTokens(authTokens.authenticationMethod, authTokens.authenticationToken, stringFromProto(authTokens.userToken), stringFromProto(authTokens.linkToken));
 }
-// The authorization header of a request, encoded. Lives here because this is the only file that
-// writes a proto field; a transport puts these bytes in the header however it wants.
+// The encoded authorization header of a request. It lives here because this file writes the proto
+// fields. A transport puts the bytes in the header.
 export function buildAuthTokensBytes(authTokens) {
     return proto_AuthTokens.toBinary(authTokens);
 }
-// How a container keeps the credentials it earned: the two tokens this server issued, with a
-// null eTag because a reissued token is not a later version of an earlier one and greater-wins
-// would refuse it.
-// The authentication token is left out however it was passed in: it belongs to the identity
-// provider, so a stored copy could only be staler than the one held in memory and would outlive
-// the sign out that should have ended it.
+// How a container keeps the credentials it earned: the two tokens this server issued. The eTag is
+// null because a reissued token is not a later version of the old one, and greater-wins would refuse
+// it. The authentication token is never stored: it belongs to the identity provider, so a copy would
+// be staler than the one in memory and would outlive the sign out.
 export function authTokensToBlob(authTokens) {
     const stored = proto_AuthTokens.create({
         authenticationMethod: authTokens.authenticationMethod,
@@ -506,8 +528,7 @@ export function authTokensFromBytes(bytes) {
 }
 // #endregion
 // #region Paging
-// What the server issued while answering, which every response of this protocol carries in the same
-// field - the two sync outs and a sync in alike.
+// What the server issued while answering. All three response types carry it in the same field.
 export function getResponseAuthTokens(response) {
     return response.authTokens;
 }
@@ -521,13 +542,13 @@ export function refreshAuthTokens(authTokens, issued) {
         result.linkToken = issued.linkToken;
     return result;
 }
-// The request that asks for the page after this response, or null when this response was the last.
-// A response carrying a full page has been cut short, so the cursors are raised from what arrived
-// and the call is repeated. A full page that raised no cursor at all can only come from a server
-// breaking the ascending order it promises; the loop is unbounded, so it stops rather than trust it.
+// The request for the page after this response, or null when it was the last. A full page was cut
+// short, so the cursors are raised from what arrived and the call repeats. A full page that raised no
+// cursor means the server broke the ascending order it promises. The loop is unbounded, so it stops
+// there.
 export function nextBusinessSyncOutRequest(request, response) {
-    // Anything short of a full page is the server saying it has sent everything it had. Counted
-    // before anything is looked at, so the ordinary answer costs no more than reading nine lengths.
+    // A short page means the server sent everything. Counting first keeps the ordinary case to nine
+    // length reads.
     if (businessResponseEntityCount(response) < proto_Constants.SYNC_OUT_LIMIT)
         return null;
     const cursors = businessSyncOutCursors(request);
@@ -560,8 +581,8 @@ export function nextBusinessSyncOutRequest(request, response) {
     const renewedExpiry = getBusinessResponseAttachmentBaseUrlExpiry(response);
     return createBusinessSyncOutRequest(request.business, cursors, renewedExpiry === 0n ? request.attachmentBaseUrlExpiry : renewedExpiry);
 }
-// The same for a profile read. Any joinBusinessId the first request carried is deliberately left
-// off the ones that follow: a join is done once, by the call that asked for it.
+// The same for a profile read. A joinBusinessId on the first request is left off the later ones,
+// since the call that asked for the join does it once.
 export function nextProfileSyncOutRequest(request, response) {
     if (profileResponseEntityCount(response) < proto_Constants.SYNC_OUT_LIMIT)
         return null;
@@ -575,15 +596,13 @@ export function nextProfileSyncOutRequest(request, response) {
     for (const business of response.businesses)
         if (raiseCursor(cursors, business.entity))
             haveCursorsRisen = true;
-    // A full page that raised nothing can only come from a server breaking the ascending order it
-    // promises; the loop is unbounded, so it stops rather than trust it
+    // A full page that raised no cursor ends the loop, as in nextBusinessSyncOutRequest
     if (!haveCursorsRisen)
         return null;
     return buildProfileSyncOutRequest(cursors);
 }
-// How many entities a response carried, without decoding or encoding any of them - a paging loop
-// asks this of every page, and getBusinessResponseEntities answers the same question only by encoding each
-// entity for the cache on the way past.
+// How many entities a response carried, without encoding any. A paging loop asks this of every page,
+// and getBusinessResponseEntities would encode each entity to answer it.
 function businessResponseEntityCount(response) {
     return ((response.business === undefined ? 0 : 1) +
         response.attachments.length +
@@ -600,9 +619,8 @@ function profileResponseEntityCount(response) {
         response.businessLinks.length +
         response.businesses.length);
 }
-// Raises the cursors the entities of one page advance, and answers the keys that moved - one for
-// all the entities of a table, however many of them raised it. A tombstone counts exactly as a value
-// does, as it does for raiseCursor.
+// Raises the cursors the entities of one page advance and answers the keys that moved, one per table
+// however many entities raised it. A tombstone counts like any entity, as in raiseCursor.
 function raiseCursorsFrom(cursors, entities) {
     const movedKeys = new Set();
     for (const entity of entities)
@@ -610,15 +628,15 @@ function raiseCursorsFrom(cursors, entities) {
             movedKeys.add(SyncKeys.keyOf(entity.entityTypeId));
     return movedKeys;
 }
-// Raises the cursor one entity advances, and answers whether it moved. A tombstone counts exactly
-// as a value does - skipping one would have the server send it again for ever.
+// Raises the cursor one entity advances and answers whether it moved. A tombstone counts, or the
+// server would send it again for ever.
 function raiseCursor(cursors, entity) {
     if (entity === undefined)
         return false;
     return cursors.raiseUpdateNumber(Ids.getEntityTypeId(entity.id), entity.updateNumber);
 }
-// The cursors a request is carrying, as a state that can be raised - the inverse of the two builders
-// above, and how a paging loop carries what it has already been sent into the call after it.
+// The cursors a request carries, as a state that can be raised: the inverse of the request builders.
+// A paging loop uses it to carry them into the next call.
 function businessSyncOutCursors(request) {
     const cursors = new SyncState(SyncKeys.BUSINESS_SYNC_IN);
     cursors.raiseUpdateNumber(proto_Constants.BUSINESS_ENTITY_TYPE_ID, request.businessUpdateNumber);
@@ -637,21 +655,20 @@ function profileSyncOutCursors(request) {
 }
 // #endregion
 // #region A response as an object graph
-// The whole of one business as an object graph, regrouping the flat wire entities by owner id so
-// each class can be constructed with its children.
-// An entity whose parent is missing is dropped, since a paged read can hold a child whose parent
-// has yet to arrive; null when the response carries no Business at all.
+// One business as an object graph, regrouping the flat wire entities by owner id so each class is
+// built with its children. An entity whose parent is missing is dropped, since a paged read can hold
+// a child before its parent arrives. Null when the response has no live Business.
 export function buildBusiness(response) {
     const businessProto = response.business;
     if (businessProto === undefined || isDeletedEntity(getEntity(businessProto.entity)))
         return null;
     const business = businessFromProto(businessProto);
     const updatableBusiness = business;
-    // A tax travels as its raw code, which means something only within the business's country - so
-    // every tax below is read against this one
+    // A tax travels as a raw code that means something only within the business's country, so every tax
+    // below is read against this one
     const countryCode = businessProto.countryCode;
-    // Resolved once here and handed to every Photo built below, since a photo takes the base url in
-    // effect when it is built rather than looking one up later - see the comment on Photo's constructor.
+    // Resolved once and handed to every Photo built below, since a Photo takes the base url when it is
+    // built - see Photo's constructor.
     const attachmentBaseUrlProto = response.attachmentBaseUrl;
     const attachmentBaseUrl = attachmentBaseUrlProto === undefined ? null : attachmentBaseUrlFromProto(attachmentBaseUrlProto);
     updatableBusiness.attachmentBaseUrl = attachmentBaseUrl;
@@ -673,10 +690,10 @@ export function buildBusiness(response) {
         updatableBusiness.settings = generalSettingsFromProto(generalSettings, countryCode);
     // The photos of the store itself
     updatableBusiness.photos = takePhotos(attachmentsByOwner, business.id, attachmentBaseUrl);
-    // Prices, by the package each applies to. Only the MeraBills Online list is this storefront's -
-    // a business prices the same package in several lists, and a price from any other one is not
-    // what it sells at here, so it is passed over rather than allowed to win a package. Within that
-    // one list a package has one price; if a second arrives anyway, the first is kept.
+    // Prices, by the package each applies to. Only the MeraBills Online list is this storefront's. A
+    // business prices a package in several lists, and a price from another list is not what it sells at
+    // here, so it is skipped. A package has one price in that list; if a second arrives, the first is
+    // kept.
     const pricesByPackage = new Map();
     for (const priceProto of response.prices) {
         if (isDeletedItem(priceProto.item))
@@ -687,10 +704,9 @@ export function buildBusiness(response) {
         if (!pricesByPackage.has(price.packageId))
             pricesByPackage.set(price.packageId, price);
     }
-    // Packages, by the product each belongs to, built with their photos and their price. A package
-    // that is not buyable - disabled, unpriced, or priced with a price that is itself disabled - is
-    // left out here rather than handed to the UI unbuyable: a product-level filter does not, by
-    // itself, guarantee every package of an otherwise visible product is itself enabled.
+    // Packages, by the product each belongs to, built with their photos and price. A package that is not
+    // buyable (disabled, unpriced, or priced with a disabled price) is left out. A product-level filter
+    // alone would not guarantee that every package of a visible product is enabled.
     const packagesByProduct = new Map();
     for (const packageProto of response.packages) {
         if (isDeletedItem(packageProto.item))
@@ -709,10 +725,9 @@ export function buildBusiness(response) {
         else
             siblings.push(pkg);
     }
-    // Products, built with their photos and their buyable packages, and parented to the business
-    // (not their category, which only groups them). A product that is not buyable - disabled, sold
-    // only offline (the server sends those, flagged), or left with no buyable package by the filtering
-    // above - is left out for the same reason.
+    // Products, built with their photos and buyable packages, and parented to the business (their
+    // category only groups them). A product that is not buyable is left out: disabled, sold only offline
+    // (the server sends those, flagged), or left with no buyable package by the filtering above.
     const products = [];
     for (const productProto of response.products) {
         if (isDeletedItem(productProto.item))
@@ -736,9 +751,9 @@ export function buildBusiness(response) {
         UpdatableEntity.setParent(productCategory, business);
         productCategories.push(productCategory);
     }
-    // The one list a storefront sells from is MeraBills Online, named rather than taken to be
-    // whichever list arrived first: the same sync can carry others, and the catalog has to answer
-    // with the list the prices above came from or a cart would name one they did not.
+    // The one list a storefront sells from is MeraBills Online, picked by id since the same sync can
+    // carry others. The catalog must answer with the list the prices above came from, or a cart would
+    // name one they are not in.
     let priceList = null;
     for (const priceListProto of response.priceLists) {
         if (isDeletedItem(priceListProto.item))
@@ -750,30 +765,30 @@ export function buildBusiness(response) {
         break;
     }
     updatableBusiness.catalog = new Catalog(productCategories, products, priceList);
-    // The orders of this customer, and their party preferences: the cart, and the fulfillment mode
-    // to default their next order to. A message of any other payload type is dropped.
+    // The orders of this customer, and their party preferences (the cart and the fulfillment mode to
+    // default the next order to). A message of any other payload type is dropped. The business completes
+    // an order by deleting its message, and the server sends that message whole, so the orders are the
+    // open and the completed ones, told apart by Order.isDeleted. A deleted message with no order (from
+    // an older server that sent only the header) is not an order.
     const orders = [];
     for (const message of response.messages) {
-        if (isDeletedEntity(getEntity(message.entity)))
-            continue;
-        // The party preferences are one message out of however many there are, so they are settled below
+        // Party preferences are one message out of possibly several, so they are settled below
         if (message.payload.oneofKind === "salesOrder")
             orders.push(orderFromProto(message, message.payload.salesOrder, countryCode));
     }
-    // One customer has one party preferences message, so two means two callers' messages are in one container. The one that is
-    // taken is the one that partyPreferencesMessageFromMessages picks, which is what a cart that is amended or sent again is
-    // read from as well: a rule of its own here would show one cart and amend another. It is the newer of the two even when it
-    // is the emptied one, and the older one's list is not shown for want of it.
+    // A customer has one party preferences message, so two means two callers' messages share a
+    // container. Take the one partyPreferencesMessageFromMessages picks, which is also what an amended or
+    // resent cart is read from. A rule of its own here would show one cart and amend another. The newer
+    // one wins even when it is the emptied one, and the older one's list is not shown.
     const partyPreferences = partyPreferencesMessageFromMessages(response.messages);
     let cart = null;
     let defaultFulfillmentMode = proto_FulfillmentMode.DELIVERY;
     if (partyPreferences !== null && partyPreferences.payload.oneofKind === "partyPreferences") {
-        // An emptied cart is a message whose payload carries no shopping list, which is what
-        // placing an order leaves behind - so it answers null and not an empty list, the same as
-        // never having had a cart at all
+        // An emptied cart is a message whose payload has no shopping list, which is what placing an order
+        // leaves. It answers null, the same as never having had a cart.
         cart = cartShoppingListFromProto(partyPreferences.payload.partyPreferences, countryCode);
-        // Whatever this same message carries, DELIVERY only ever coming from the fallback above -
-        // not from a message that happens to hold UNSPECIFIED_FULFILLMENT_MODE itself
+        // Taken as the message has it. DELIVERY comes only from the fallback above, even when the message
+        // holds UNSPECIFIED_FULFILLMENT_MODE.
         defaultFulfillmentMode = partyPreferences.payload.partyPreferences.fulfillmentMode;
     }
     for (const order of orders)
@@ -813,11 +828,9 @@ export function buildOrder(message, countryCode) {
         return null;
     return orderFromProto(message, message.payload.salesOrder, countryCode);
 }
-// The shopping list a cart message carries, empty rather than absent when the cart has been
-// emptied. Unlike Business.cart (see the party preferences case of buildBusiness, which answers
-// null so "emptied" and "never had one" look the same to a customer), a caller here - createOrder,
-// the visitor cart carried over on sign in - works with an actual list either way.
-// countryCode is that of the business the cart is for, as for buildOrder.
+// The shopping list a cart message carries, empty when the cart was emptied. Business.cart answers
+// null for that (see buildBusiness), but the callers here, createOrder and the visitor cart carried
+// over on sign in, need an actual list. countryCode is the cart's business, as for buildOrder.
 export function buildShoppingList(message, countryCode) {
     if (message.payload.oneofKind !== "partyPreferences")
         throw new InvalidArgumentException("That message carries no party preferences, so it is not a cart");
@@ -826,37 +839,29 @@ export function buildShoppingList(message, countryCode) {
 // #endregion
 // #region What a customer pushes
 //
-// The only direction of this file that encodes rather than decodes, and the only entity type a
-// storefront may write: a Message, carrying either the cart or an order placed from it. Two rules
-// hold for both, and they are what make a pushed message storable here as well as on the server.
-// The first is that the id is the client's: a sync in answers with an update number and no id, so a
-// message the server named could never be found here again. The second is that updatedAt is the
-// client's too and the server keeps it unchanged - so the copy stored here carries the same eTag as
-// the copy a later read would bring back, and neither can look stale to the other.
-// The party preferences of this customer as a message to push, carrying the cart and (optionally)
-// the fulfillment mode both. An existing message is amended rather than rebuilt, because its
-// payload can carry fields neither param here speaks to, and losing them would be a storefront
-// overwriting data it cannot even read.
-// Its id is used in preference to the derived one for the same reason: that is where the server
-// already holds this customer's party preferences, and it is only worth deriving an id when there
-// is none to amend.
-// A list holding nothing is pushed as no list at all, the way Java serializeShoppingList answers
-// null below one item - so emptying a cart and never having had one are one state on the wire, and
-// placing an order is what puts a cart into it.
-// fulfillmentMode is null to leave whatever is already there alone - the ordinary case, since a
-// storefront otherwise treats it as the merchant app's own data - and a value only where createOrder
-// means to set it, to the mode of the order that just emptied this cart.
+// A storefront writes one entity type, a Message carrying the cart or an order placed from it. Two
+// rules hold for both, so a pushed message is storable here as well as on the server. The id is the
+// client's: a sync in answers with an update number and no id, so a message the server named could
+// not be found here again. updatedAt is the client's too and the server keeps it, so the copy stored
+// here has the same eTag as the one a later read brings back.
+// This customer's party preferences as a message to push, carrying the cart and optionally the
+// fulfillment mode. An existing message is amended, since its payload can carry fields a storefront
+// cannot read, and dropping them would overwrite that data. Its id is kept, as the server holds the
+// preferences under it. The derived id is used only when there is nothing to amend.
+// A list with no items is pushed as no list, as Java serializeShoppingList answers null below one
+// item. Emptying a cart and never having had one are one state on the wire.
+// fulfillmentMode null leaves the existing value alone, the ordinary case: a storefront treats it as
+// the merchant app's data. createOrder sets it to the mode of the order that just emptied the cart.
 export function buildPartyPreferencesMessage(messageId, existing, senderId, shoppingList, fulfillmentMode, now) {
     const existingEntity = existing === null ? null : getEntity(existing.entity);
     const preferences = existing !== null && existing.payload.oneofKind === "partyPreferences"
         ? existing.payload.partyPreferences
         : proto_PartyPreferencesPayload.create();
-    // Later than the copy it replaces, whatever this client's clock reads. An amendment written here
-    // without the server is stored at the update number of the copy it amends, where this field is
-    // what decides - so a client whose clock sits behind the time on the cart it is amending, which
-    // Constants.MAX_CLOCK_SKEW says is a thing that happens, would have its own store refuse the
-    // edit, leaving the customer looking at a cart that is not the one it holds. One millisecond past
-    // the copy being replaced is enough, and the server keeps whatever is sent, so both sides still agree.
+    // Later than the copy it replaces, whatever this client's clock reads. An amendment written without
+    // the server is stored at the update number of the copy it amends, so updatedAt decides. A client
+    // clock behind that copy (Constants.MAX_CLOCK_SKEW says it happens) would have its own store refuse
+    // the edit and leave the customer looking at a stale cart. One millisecond past the copy is enough,
+    // and the server keeps what is sent, so both sides agree.
     const updatedAt = existingEntity === null || existingEntity.updatedAt < now ? now : existingEntity.updatedAt + 1n;
     const partyPreferences = proto_PartyPreferencesPayload.create({
         ...preferences,
@@ -872,13 +877,12 @@ export function buildPartyPreferencesMessage(messageId, existing, senderId, shop
         payload: { oneofKind: "partyPreferences", partyPreferences: partyPreferences },
     });
 }
-// One order as a message to push. Its shopping list goes out final whatever was passed in, which is
-// what Java SalesOrderViewModel.saveChanges does before creating one: an order is what a customer
-// has finished choosing, and only a final list tracks a later change as a change rather than
-// silently altering what was ordered.
-// The two totals are filled in here from the list, and are what a fulfilled order is left with once
-// the business has cleared the list itself - so they are written off the items actually being sent
-// rather than off the counts the list carries, which a caller could have set to anything.
+// One order as a message to push. Its shopping list goes out final whatever the list says, as Java
+// SalesOrderViewModel.saveChanges does before creating an order: the customer has finished choosing,
+// and only a final list tracks a later change as a change instead of silently altering what was
+// ordered. The two totals are all that remains of an order completed by an older merchant app, which
+// moved the list out of the order. They are filled from the list being sent, not from the counts it
+// carries, which a caller could set to anything.
 export function buildOrderMessage(orderId, senderId, shoppingList, fulfillmentMode, deliveryAddressId, deliveryAddress, note, creationDate) {
     return proto_Message.create({
         entity: pushedEntity(orderId, creationDate, creationDate),
@@ -901,36 +905,31 @@ export function buildOrderMessage(orderId, senderId, shoppingList, fulfillmentMo
         },
     });
 }
-// A sync in response's messages as the cache write they make, tombstones included - the same as any
-// other entity array this library reads off the wire. This is how a push's own messages end up
-// stored under the update numbers the server just assigned them, with no separate stamping step:
-// the response already carries them as full entities, not as a bare number to reapply by hand.
+// The messages of a sync in response as a cache write, tombstones included like any other entity
+// array. This stores a push's own messages under the update numbers the server just assigned, with no
+// separate stamping step, since the response carries full entities.
 export function messagesToCacheWrite(messages) {
     return toCacheWrite(messages.map((message) => toWireEntity(message.entity, proto_Message.toBinary(message))));
 }
-// The Entity of something this client is pushing. The update number goes out as zero: the protocol
-// replaces a caller's own with the server's and answers what it assigned, so there is nothing to
-// send and nothing to guess. It is also what a message not pushed yet is left holding in the store,
-// where messageToBlob versions it from the copy it amends. updateInfo goes out as zero too: it
-// would be the id of the store that made the change, and this client has no store of its own that
-// the server knows. It needs none: a read of this business sends these messages back, as the
-// server leaves nobody's changes out of a storefront's read, and the eTag of the copy stored here
-// is the one the server kept, so, that changes nothing it holds.
+// The Entity of something this client is pushing. The update number goes out as zero: the server
+// replaces a caller's own with the one it assigns, so there is nothing to send. A message not pushed
+// yet is stored holding zero, and messageToBlob versions it from the copy it amends. updateInfo is
+// zero too, as it would be the id of the store that made the change and the server knows no store of
+// this client. It needs none: a read sends these messages back (the server leaves no one's changes
+// out of a storefront's read), and the eTag stored here is the one the server kept, so the read
+// changes nothing.
 function pushedEntity(id, createdAt, updatedAt) {
     return proto_Entity.create({ id: id, createdAt: createdAt, updatedAt: updatedAt });
 }
-// Whether shoppingList differs from what stored already holds, so updateCart can check before
-// building or pushing a cart message rather than after - a caller may call it on every event it
-// cares about and only a cart the server has not got costs a request.
-// Compares raw lists rather than built messages, because a message's updatedAt always differs from
-// call to call; sound because the server echoes a pushed list back with the items it was sent, so what
-// is stored is what was last sent - but not in the order it was sent in: the server keeps the items of a
-// list by package id and sends them in that order, and the order of the list is each item's
-// shoppingListOrder, which is compared with the rest of the item. So the items of both lists are put
-// in package id order before they are compared, or a cart that was not picked in package id order would
-// differ from its own echo and be pushed again, which re-stamps its updatedAt for every other device.
-// Also true whenever stored has never been pushed (updateNumber 0, left by updateCartLocalOnly),
-// regardless of content, so an unsent local edit still goes out.
+// Whether shoppingList differs from what stored holds, so updateCart can skip a push. Compares raw
+// lists, since a message's updatedAt differs on every call. That is sound because the server echoes
+// a pushed list back with the items it was sent, so stored is what was last sent.
+// The server echoes the items in package id order, and the list's own order is each item's
+// shoppingListOrder, compared with the item. So both lists are put in package id order first, or a
+// cart not picked in that order would differ from its echo and be pushed again, re-stamping
+// updatedAt for every other device.
+// True also when stored was never pushed (updateNumber 0, left by updateCartLocalOnly), so an
+// unsent local edit still goes out.
 export function hasShoppingListChanged(stored, shoppingList) {
     if (stored === null)
         return pushedShoppingList(shoppingList, false) !== undefined;
@@ -949,15 +948,14 @@ function inPackageIdOrder(list) {
         deletedItems: [...list.deletedItems].sort(byPackageId),
     });
 }
-// The list inside a cart message, or absent for one carrying no list - which is an emptied cart
+// The list inside a cart message, or absent for an emptied cart
 function getCartShoppingList(message) {
     return message.payload.oneofKind === "partyPreferences"
         ? message.payload.partyPreferences.shoppingList
         : undefined;
 }
-// A shopping list on its way out, or absent when it holds nothing - see
-// buildPartyPreferencesMessage. Emptiness is judged by the items being sent and not by the counts
-// the list carries, for the reason the counts below are.
+// A shopping list on its way out, or absent when it holds nothing - see buildPartyPreferencesMessage.
+// Emptiness is judged by the items sent, not the counts, for the reason given at shoppingListToProto.
 function pushedShoppingList(shoppingList, isFinal) {
     if (shoppingList === null)
         return undefined;
@@ -965,10 +963,9 @@ function pushedShoppingList(shoppingList, isFinal) {
         return undefined;
     return shoppingListToProto(shoppingList, isFinal);
 }
-// The counts are written off the arrays rather than copied from the list. A read takes them from the
-// wire because the protocol sends a count even where it does not send the items, but a push always
-// sends the items - so the arrays are what is true here, and taking the counts from them is what
-// makes it impossible to push a list whose count disagrees with its contents.
+// The counts come from the arrays, not the list. A read takes them from the wire because the
+// protocol sends a count even where it omits the items, but a push always sends the items. Taking the
+// counts from the arrays means a pushed list cannot disagree with its contents.
 function shoppingListToProto(shoppingList, isFinal) {
     return proto_ShoppingList.create({
         isFinal: isFinal,
@@ -984,9 +981,8 @@ function shoppingListToProto(shoppingList, isFinal) {
         deletedItems: shoppingList.deletedItems.map(shoppingListItemToProto),
     });
 }
-// The mirror of shoppingListItemFromProto: everything the model holds unscaled goes back scaled, and
-// nothing derived is sent - amount, totalTax and finalPrice are computed from these fields, here and
-// by the server both.
+// The mirror of shoppingListItemFromProto. Unscaled model values go back scaled, and nothing derived
+// is sent: amount, totalTax and finalPrice are computed from these fields on both sides.
 function shoppingListItemToProto(item) {
     return proto_ShoppingListItem.create({
         packageId: item.packageId,
@@ -1008,12 +1004,12 @@ function taxToProto(tax) {
 }
 // #endregion
 // #region Entity and item bookkeeping
-// One pass over the entities of a response, each becoming a blob at its own id, which is what makes
-// one read of a container enough to sort it by entity type. Every blob is versioned by entityETag, a
-// tombstone's too: a delete is a write of its own, so a tombstone carries a greater update number
-// than any copy of what it deleted and replaces it, and an older copy of it, sent again, is the
-// lesser of the two and is refused. A later write of the same id is the greater again, and is kept.
-// Mutable arrays, so that businessResponseToCacheWrite can add the attachment base url to the blobs.
+// One pass over a response's entities, each becoming a blob at its own id, so one read of a container
+// is enough to sort it by entity type. Every blob is versioned by entityETag, tombstones too. A
+// delete is a write of its own, so a tombstone has a greater update number than any copy of what it
+// deleted and replaces it. An older copy sent again is lesser and refused, and a later write of the
+// same id is greater and kept. The arrays are mutable so that businessResponseToCacheWrite can add
+// the attachment base url.
 function toCacheWrite(entities) {
     const blobs = [];
     for (const entity of entities)
@@ -1024,23 +1020,23 @@ function toCacheWrite(entities) {
         });
     return { blobs: blobs, deletedIds: [] };
 }
-// What a store versions the blob of an entity by: its update number, and below it its updatedAt, in
-// one bigint so that the greater wins as the store says. The server assigns an update number to every
-// write, deletes included, so it rises with every change to an entity whatever any clock reads, and
-// decides between two copies that are not the same version. updatedAt decides between those that
-// are: only a copy this client wrote itself, at the update number of the one it amended, is another
-// of the same number. Wider than 64 bits, which a bigint holds exactly and a store must compare as one.
+// What a store versions an entity's blob by: the update number, with updatedAt below it, in one
+// bigint so the greater wins as the store says. The server assigns an update number to every write,
+// deletes included, so it rises with every change whatever any clock reads, and decides between
+// different versions. updatedAt decides between copies of one update number. Only a copy this client
+// wrote itself, at the update number of the one it amended, shares one. The value is wider than 64
+// bits, which a bigint holds exactly and a store must compare as one.
 export function entityETag(updateNumber, updatedAt) {
     if (updateNumber < 0n || updatedAt < 0n)
         throw new InvalidArgumentException("An update number and an updatedAt are never negative");
     return (updateNumber << UPDATED_AT_BITS) | updatedAt;
 }
-// A message this client wrote, which has no update number of its own until a server assigns one, and
-// has none in the store as long as it is not pushed (see pushedEntity). It is versioned at the update
-// number of the copy it amends, which is the one heldETag carries, and so it is the later copy of that
-// version by its updatedAt: a copy of the version it amends, sent again by the server, is not, and a
-// later version of the server's, with a greater update number, replaces it. One that amends nothing
-// is at zero. A message that has an update number of its own is versioned by it, as any entity is.
+// A message this client wrote has no update number until a server assigns one, and has none in the
+// store while unpushed (see pushedEntity). It is versioned at the update number of the copy it
+// amends, which heldETag carries, so by its updatedAt it is the later copy of that version. The
+// server sending the amended copy again does not replace it, but a later server version with a
+// greater update number does. A message that amends nothing is at zero. A message with an update
+// number of its own is versioned by it, as any entity is.
 function messageToBlob(message, heldETag) {
     const entity = getEntity(message.entity);
     const updateNumber = entity.updateNumber !== 0n
@@ -1054,10 +1050,10 @@ function messageToBlob(message, heldETag) {
         bytes: proto_Message.toBinary(message),
     };
 }
-// The messages a container holds that are messages: a tombstone is held, and is not one. It is left out
-// whatever it carries, and not by what is found in it - a payload says what a message is, and a
-// tombstone sent by a server that left the payload on it would otherwise be read as a cart or an order.
-function messagesFromBlobs(blobs) {
+// The messages a container holds that are deleted (isDeleted) or live. Only the update number says
+// which, never what a message carries. A deleted message is a completed order when it carries one,
+// and is never a customer's cart. Each as stored.
+function messagesFromBlobs(blobs, isDeleted = false) {
     const result = [];
     for (const blob of blobs) {
         if (blob.id < 0n)
@@ -1065,7 +1061,7 @@ function messagesFromBlobs(blobs) {
         if (Ids.getEntityTypeId(blob.id) !== proto_Constants.MESSAGE_ENTITY_TYPE_ID)
             continue;
         const message = proto_Message.fromBinary(blob.bytes);
-        if (!isDeletedEntity(getEntity(message.entity)))
+        if (isDeletedEntity(getEntity(message.entity)) === isDeleted)
             result.push(message);
     }
     return result;
@@ -1115,12 +1111,12 @@ function getItemId(item) {
 }
 // #endregion
 // #region Values
-// An absent optional string is null and not empty, because Java tells the two apart
+// An absent optional string is null, because Java tells absent from empty
 function stringFromProto(value) {
     return value === undefined ? null : value;
 }
-// The way back. An empty string goes out absent as well: the two mean the same thing to a caller
-// that had nothing to say, and sending one of them would have the field come back as the other.
+// The way back. An empty string goes out absent too: the two mean the same, and sending one could
+// bring the field back as the other.
 function stringToProto(value) {
     return value === null || value.length === 0 ? undefined : value;
 }
@@ -1130,9 +1126,9 @@ function attachmentBaseUrlFromProto(urlAndToken) {
 function addressFromProto(address) {
     return new Address(address.id, address.addressType, stringFromProto(address.unitNumber), stringFromProto(address.community), stringFromProto(address.line2), stringFromProto(address.city), stringFromProto(address.state), stringFromProto(address.pinCode), address.countryCode);
 }
-// The way back, for a delivery address a customer sends out directly rather than by id - see
-// buildOrderMessage. id is sent as whatever Address carries, though it means nothing outside the
-// list it was read from and this address belongs to none.
+// The way back, for a delivery address sent directly instead of by id - see buildOrderMessage. id is
+// whatever Address carries, though it means nothing outside the list it was read from, and this
+// address is in none.
 function addressToProto(address) {
     return proto_Address.create({
         id: address.id,
@@ -1146,7 +1142,7 @@ function addressToProto(address) {
         countryCode: address.countryCode,
     });
 }
-// The way back, for the addresses of a user being sent to the server rather than read from it.
+// The way back, for the addresses of a user sent to the server.
 function addressListToProto(addressList) {
     return proto_AddressList.create({
         defaultAddressId: addressList.defaultAddressId,
@@ -1158,8 +1154,8 @@ function addressListFromProto(addressList) {
         return AddressList.EMPTY;
     return new AddressList(addressList.defaultAddressId, Object.freeze(addressList.addresses.map(addressFromProto)));
 }
-// The wire carries a tax's raw code, meaningful only within a country - that of the business the tax
-// is on, which every caller therefore has to name
+// The wire carries a tax's raw code, meaningful only within a country, so every caller names that of
+// the business the tax is on.
 function taxFromProto(tax, countryCode) {
     return Tax.fromScaledValues(countryCode, tax.taxCode, tax.rate);
 }
@@ -1193,11 +1189,11 @@ function workingHoursRangeFromProto(range) {
 function workingHoursFromProto(workingHours) {
     return new WorkingHours(Object.freeze(workingHours.ranges.map(workingHoursRangeFromProto)));
 }
-// An absent WorkingDays means the business works every day, all day - the Java default, not "no day at all"
+// An absent WorkingDays means the business works every day, all day (the Java default)
 function workingDaysFromProto(workingDays) {
     if (workingDays === undefined)
         return WorkingDays.ALL_DAYS;
-    // Not an optional field, so an unspecified zone arrives as an empty string rather than absent
+    // Not an optional field, so an unspecified zone arrives as an empty string
     return new WorkingDays(Object.freeze([...workingDays.days]), workingDays.timeZone.length === 0 ? null : workingDays.timeZone, Object.freeze(workingDays.workingHours.map(workingHoursFromProto)));
 }
 function shoppingListItemFromProto(item, countryCode) {
@@ -1266,20 +1262,18 @@ function orderFromProto(message, salesOrder, countryCode) {
     const entity = getEntity(message.entity);
     return Order.fromScaledValues(toEntityHeader(entity), message.senderId, message.status, stringFromProto(message.senderName), stringFromProto(message.senderPhone), salesOrder.status, salesOrder.fulfillmentMode, shoppingListFromProto(salesOrder.shoppingList, countryCode), salesOrder.shoppingListTotal, salesOrder.shoppingListCount, salesOrder.deliveryAddressId, salesOrder.deliveryAddress === undefined ? null : addressFromProto(salesOrder.deliveryAddress), salesOrder.creationDate, stringFromProto(salesOrder.note), salesOrder.paymentReceived);
 }
-// The one part of a cart message a customer is shown. Absent rather than empty when the cart holds
-// nothing, so that "emptied by placing an order" and "never had one" are the same answer - which is
-// also what makes createOrder's emptied cart indistinguishable from a cart that was never created.
-// Everything else the message carries is the server's: who sent it, how far the business has got
-// with reading it, and the fulfillment mode Java keeps there, which belongs to an order here.
+// The one part of a cart message a customer is shown. Null when the cart holds nothing, so a cart
+// emptied by placing an order and one never created give the same answer. The rest of the message is
+// the server's or read elsewhere: who sent it, how far the business has read it, and the fulfillment
+// mode, which buildBusiness reads as defaultFulfillmentMode.
 function cartShoppingListFromProto(partyPreferences, countryCode) {
     const shoppingList = partyPreferences.shoppingList;
     return shoppingList === undefined ? null : shoppingListFromProto(shoppingList, countryCode);
 }
 // #endregion
 // #region Photos
-// The photos of one entity, in no particular order - a UI orders these for display. Each is built
-// with the base url resolved for this response, since a Photo takes it at construction rather than
-// looking it up later.
+// The photos of one entity, in no particular order (a UI orders them). Each is built with the
+// response's base url, since a Photo takes it at construction.
 function takePhotos(attachmentsByOwner, owningEntityId, attachmentBaseUrl) {
     const attachments = attachmentsByOwner.get(owningEntityId);
     if (attachments === undefined)