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

package/dist/ProtoMap.js

@@ -98,12 +98,12 @@ export function getProfileResponseEntities(response) {
         result.push(toWireEntity(business.entity, proto_Business.toBinary(business)));
     return result;
 }
-// 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).
+// One blob per entity, tombstones included and as sent, plus a blob for the attachment base url,
+// which belongs to the business and has no entity.
 export function businessResponseToCacheWrite(response) {
     const write = toCacheWrite(getBusinessResponseEntities(response));
-    // 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.
+    // The url's 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({
@@ -122,9 +122,10 @@ export function profileResponseToCacheWrite(response) {
 export function getBusinessResponseAttachmentBaseUrlExpiry(response) {
     return response?.attachmentBaseUrl?.expiry ?? 0n;
 }
-// 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.
+// One order as a blob, for a caller holding a message rather than a response. Only the payload says
+// whether a message is an order, so a message without a sales order throws here instead of being
+// 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");
@@ -134,8 +135,8 @@ export function orderToBlob(order, heldETag) {
 export function isPartyPreferencesMessage(message) {
     return message.payload.oneofKind === "partyPreferences";
 }
-// When a message was last written. It compares two copies of one thing held at different ids, which
-// have no shared version.
+// When a message was last written. Use it to order two copies of one thing held at different ids,
+// which have no shared version.
 export function getMessageUpdatedAt(message) {
     return getEntity(message.entity).updatedAt;
 }
@@ -149,8 +150,8 @@ export function partyPreferencesToBlob(partyPreferences, heldETag) {
     return messageToBlob(partyPreferences, heldETag);
 }
 // 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.
+// hold nothing yet. The entity type is part of each blob id and picks the array a blob goes in, 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;
@@ -260,9 +261,9 @@ 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.
+// order by deleting its message, so these are tombstones. The server sends them whole because the
+// customer is shown the order afterwards. A tombstone without an order (from an older server that
+// sent only the header) is skipped.
 export function deletedOrderMessagesFromBlobs(blobs) {
     return ordersAmong(messagesFromBlobs(blobs, true));
 }
@@ -270,12 +271,13 @@ 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.
+// two mean that two callers' messages share a container. The one with the greater update number is
+// returned, an arbitrary choice 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.
+// buildBusiness uses it too, so the cart that is shown, amended and carried over at sign in always
+// comes from the same message.
 export function partyPreferencesMessageFromMessages(messages) {
     let result = null;
     for (const message of messages) {
@@ -297,9 +299,9 @@ export function partyPreferencesMessageFromBlobs(blobs) {
 // #endregion
 // #region Requests and credentials
 // 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).
+// id, which a caller that has read the business before holds. A string is its url friendly
+// businessId, the only identifier a first read has. attachmentBaseUrlExpiry is not one of the
+// cursors. It is 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 }
@@ -333,9 +335,9 @@ export function cursorsToBlobs(cursors, movedKeys) {
     return blobs;
 }
 // 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.
+// none). A container never read, or filled by a version that kept no cursors, gets zeros, so the
+// next read fetches everything again. That costs only bandwidth, 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()) {
@@ -345,15 +347,15 @@ export function cursorsFromBlobs(keys, blobs) {
     }
     return cursors;
 }
-// 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.
+// Raises the cursors to what a page of a business read brought, tombstones included, and returns the
+// keys that moved. Only a read moves them. A push does not.
 export function raiseBusinessCursors(cursors, response) {
     return raiseCursorsFrom(cursors, getBusinessResponseEntities(response));
 }
-// The request that pushes what this customer changed. A storefront may push only messages, and one
+// The request that pushes what this customer changed. A storefront may push only messages. 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.
+// with 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,
@@ -366,10 +368,10 @@ export function getSyncInResponseMessages(response) {
     return response.messages;
 }
 // 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.
+// business, since a profile sync is not scoped to one and has no sync in. joinBusinessId is the
+// entity id of a business to make the caller a customer of while the server answers.
+// Constants.ENTITY_ID_NULL means 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),
@@ -382,8 +384,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. It has no entity yet (the
-// server assigns id, createdAt and updatedAt), so none of EntityHeader goes out.
+// The user a sign up sends as CreateUserRequest.user, for the server to create. It has no entity yet
+// (the server assigns id, createdAt and updatedAt), so none of EntityHeader is sent.
 export function buildUser(userProfile) {
     return proto_User.create({
         firstName: userProfile.firstName,
@@ -393,18 +395,18 @@ export function buildUser(userProfile) {
         preferredLanguageCode: stringToProto(userProfile.preferredLanguageCode),
     });
 }
-// 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.
+// The user that Service.updateUser writes over this customer's profile: the fields of buildUser plus
+// the entity id, which the server matches to the caller. 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 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 two things a response to a join must hold, checked separately so a caller can report which one
+// is missing - see Model.requireJoinedBusiness. Both 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.
@@ -424,7 +426,7 @@ export function hasJoinedBusinessLink(joinBusinessId, response) {
 export function hasJoinedBusiness(joinBusinessId, response) {
     if (joinBusinessId === BigInt(proto_Constants.ENTITY_ID_NULL))
         return false;
-    // A tombstone is not the business, which is what the join is answered with
+    // A tombstoned business does not count
     for (const business of response.businesses)
         if (getEntity(business.entity).id === joinBusinessId &&
             !isDeletedEntity(getEntity(business.entity)))
@@ -432,8 +434,8 @@ export function hasJoinedBusiness(joinBusinessId, response) {
     return false;
 }
 // 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.
+// A tombstone has no country, and a bare header carries zero. Zero must not be taken for a country,
+// because 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)))
@@ -441,8 +443,8 @@ export function getBusinessResponseCountryCode(response) {
     return business.countryCode;
 }
 // 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.
+// Once a business has been read, later requests name it by this id, which is stable. The url
+// friendly id is used only to find the business the first time.
 export function getBusinessResponseBusinessEntityId(response) {
     const entity = response?.business?.entity;
     if (entity === undefined || isDeletedEntity(entity))
@@ -465,9 +467,9 @@ export function isBusinessResponseOnlineShoppingOn(response) {
         return false;
     return getGeneralSettingsOf(response)?.onlineShoppingEnabled ?? false;
 }
-// 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.
+// The general settings a response holds, as on the wire, or undefined when none. They come from the
+// one public configuration that carries them, unless it is deleted. buildBusiness and
+// isBusinessResponseOnlineShoppingOn both read them here, so both use the same settings.
 function getGeneralSettingsOf(response) {
     let settings;
     for (const configuration of response.configurations) {
@@ -480,7 +482,7 @@ function getGeneralSettingsOf(response) {
     return settings;
 }
 // The credentials of one call, as on the wire. An absent token is left off the message, since the
-// protocol tells absent from empty.
+// protocol distinguishes absent from empty.
 export function buildAuthTokens(authTokens) {
     const result = proto_AuthTokens.create({
         authenticationMethod: authTokens.authenticationMethod,
@@ -503,10 +505,10 @@ export function authTokensFromProto(authTokens) {
 export function buildAuthTokensBytes(authTokens) {
     return proto_AuthTokens.toBinary(authTokens);
 }
-// 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.
+// The credentials as a container stores them: the two tokens this server issued, and the
+// authentication method. 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,
@@ -542,13 +544,13 @@ export function refreshAuthTokens(authTokens, issued) {
         result.linkToken = issued.linkToken;
     return result;
 }
-// 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.
+// The request for the page after this response, or null when it was the last. A full page may have
+// been 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 has no other
+// bound, so it ends there.
 export function nextBusinessSyncOutRequest(request, response) {
     // A short page means the server sent everything. Counting first keeps the ordinary case to nine
-    // length reads.
+    // field reads.
     if (businessResponseEntityCount(response) < proto_Constants.SYNC_OUT_LIMIT)
         return null;
     const cursors = businessSyncOutCursors(request);
@@ -577,12 +579,12 @@ export function nextBusinessSyncOutRequest(request, response) {
         raise(getItem(price.item).entity);
     if (!haveCursorsRisen)
         return null;
-    // A page that renewed the url means a later one is now held; otherwise what was sent still stands
+    // Use the expiry of a renewed url if this page carried one, else the expiry already sent
     const renewedExpiry = getBusinessResponseAttachmentBaseUrlExpiry(response);
     return createBusinessSyncOutRequest(request.business, cursors, renewedExpiry === 0n ? request.attachmentBaseUrlExpiry : renewedExpiry);
 }
 // 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.
+// since the first call makes the join.
 export function nextProfileSyncOutRequest(request, response) {
     if (profileResponseEntityCount(response) < proto_Constants.SYNC_OUT_LIMIT)
         return null;
@@ -601,8 +603,8 @@ export function nextProfileSyncOutRequest(request, response) {
         return null;
     return buildProfileSyncOutRequest(cursors);
 }
-// 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.
+// How many entities a response carried, counted without encoding any. A paging loop needs the count
+// for every page, and getBusinessResponseEntities would encode each entity to produce it.
 function businessResponseEntityCount(response) {
     return ((response.business === undefined ? 0 : 1) +
         response.attachments.length +
@@ -619,7 +621,7 @@ 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 per table
+// Raises the cursors the entities of one page advance and returns the keys that moved, each once
 // however many entities raised it. A tombstone counts like any entity, as in raiseCursor.
 function raiseCursorsFrom(cursors, entities) {
     const movedKeys = new Set();
@@ -628,8 +630,8 @@ 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, or the
-// server would send it again for ever.
+// Raises the cursor one entity advances and returns whether it moved. A tombstone counts, because
+// otherwise the server would send it again forever.
 function raiseCursor(cursors, entity) {
     if (entity === undefined)
         return false;
@@ -690,9 +692,9 @@ 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
+    // Prices, by the package each applies to. This storefront uses only the MeraBills Online list. 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
+    // 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) {
@@ -751,9 +753,9 @@ export function buildBusiness(response) {
         UpdatableEntity.setParent(productCategory, business);
         productCategories.push(productCategory);
     }
-    // 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.
+    // A storefront sells from the MeraBills Online list only, picked by id since the same sync can
+    // carry others. The catalog must hold the list the prices above came from. Otherwise a cart would
+    // name a list that does not contain them.
     let priceList = null;
     for (const priceListProto of response.priceLists) {
         if (isDeletedItem(priceListProto.item))
@@ -767,25 +769,25 @@ export function buildBusiness(response) {
     updatableBusiness.catalog = new Catalog(productCategories, products, priceList);
     // 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.
+    // an order by deleting its message, and the server sends that message whole, so the orders include
+    // the open and the completed ones. Order.isDeleted tells them apart. A deleted message without an
+    // order (from an older server that sent only the header) is skipped.
     const orders = [];
     for (const message of response.messages) {
         // 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));
     }
-    // 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.
+    // A customer has one party preferences message, so two mean two callers' messages share a
+    // container. Use the one partyPreferencesMessageFromMessages picks, which is also the one an amended
+    // or resent cart is read from. A separate rule here would show one cart and amend another. The newer
+    // message wins even when its cart is empty, 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 has no shopping list, which is what placing an order
-        // leaves. It answers null, the same as never having had a cart.
+        // leaves. The cart is null then, the same as for a customer who never had one.
         cart = cartShoppingListFromProto(partyPreferences.payload.partyPreferences, countryCode);
         // Taken as the message has it. DELIVERY comes only from the fallback above, even when the message
         // holds UNSPECIFIED_FULFILLMENT_MODE.
@@ -821,16 +823,16 @@ export function buildProfile(profileId, response) {
         return null;
     return new Profile(profileId, user, businessLinks, businesses);
 }
-// One order on its own, for a caller holding a message rather than a whole response. The country of
-// the business it was placed with is the caller's to give, since a tax travels as a raw code.
+// One order on its own, for a caller holding a message rather than a whole response. The caller
+// passes the country of the business the order was placed with, since a tax travels as a raw code.
 export function buildOrder(message, countryCode) {
     if (message.payload.oneofKind !== "salesOrder")
         return null;
     return orderFromProto(message, message.payload.salesOrder, countryCode);
 }
-// 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.
+// The shopping list a cart message carries, empty when the cart was emptied. Business.cart is null
+// then (see buildBusiness), but the callers here, createOrder and the visitor cart carried over on
+// sign in, need a list. countryCode is the country of 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");
@@ -840,28 +842,29 @@ export function buildShoppingList(message, countryCode) {
 // #region What a customer pushes
 //
 // 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.
+// rules hold for both, so a pushed message is storable here as well as on the server. The client
+// chooses the id: a sync in returns an update number and no id, so a message the server named could
+// not be found here again. The client also sets updatedAt 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.
+// A list with no items is pushed as no list, as Java serializeShoppingList returns null below one
+// item. An emptied cart and a cart never created look the same on the wire.
+// fulfillmentMode null keeps the existing value, the ordinary case: a storefront treats that field
+// as the merchant app's data and leaves it alone. createOrder sets it to the mode of the order that
+// 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 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.
+    // Later than the copy it replaces, even if this client's clock is behind it. 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 (clocks do differ, see Constants.MAX_CLOCK_SKEW) would make 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,
@@ -877,12 +880,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 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.
+// One order as a message to push. Its shopping list is sent as final regardless of the list's
+// isFinal, as Java SalesOrderViewModel.saveChanges does before creating an order: the customer has
+// finished choosing, and only a final list records a later edit as a change instead of 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),
@@ -906,30 +909,30 @@ export function buildOrderMessage(orderId, senderId, shoppingList, fulfillmentMo
     });
 }
 // 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
+// array. This stores a push's own messages under the update numbers the server 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 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.
+// The Entity of something this client is pushing. The update number goes out as zero, since the
+// server replaces a caller's own with the one it assigns. A message not pushed yet is stored holding
+// zero, and messageToBlob versions it from the copy it amends. updateInfo is zero too: it would be
+// the id of the store that made the change, and the server knows no store of this client. This
+// client does not need it: 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 storing what the
+// read brings back changes nothing.
 function pushedEntity(id, createdAt, updatedAt) {
     return proto_Entity.create({ id: id, createdAt: createdAt, updatedAt: updatedAt });
 }
 // 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.
+// lists, since a message's updatedAt differs on every call. That works 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 kept in each item's
+// shoppingListOrder, which is compared with the item. So both lists are put in package id order
+// first. Otherwise a cart not picked in that order would differ from its echo and be pushed again,
+// which re-stamps updatedAt for every other device.
+// Also true when stored was never pushed (updateNumber 0, left by updateCartLocalOnly), so an
+// unsent local edit is still pushed.
 export function hasShoppingListChanged(stored, shoppingList) {
     if (stored === null)
         return pushedShoppingList(shoppingList, false) !== undefined;
@@ -937,7 +940,7 @@ export function hasShoppingListChanged(stored, shoppingList) {
         return true;
     return !proto_ShoppingList.equals(inPackageIdOrder(getCartShoppingList(stored)), inPackageIdOrder(pushedShoppingList(shoppingList, false)));
 }
-// The same list with its items by package id, the order in which the server sends them
+// The same list with its items sorted by package id, the order the server sends them in
 function inPackageIdOrder(list) {
     if (list === undefined)
         return undefined;
@@ -954,7 +957,7 @@ function getCartShoppingList(message) {
         ? message.payload.partyPreferences.shoppingList
         : undefined;
 }
-// A shopping list on its way out, or absent when it holds nothing - see buildPartyPreferencesMessage.
+// A shopping list to push, 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)
@@ -963,9 +966,9 @@ function pushedShoppingList(shoppingList, isFinal) {
         return undefined;
     return shoppingListToProto(shoppingList, isFinal);
 }
-// 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.
+// The counts are the lengths of the item arrays, not the list's own counts. 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. Counting the arrays means a pushed list cannot disagree with its contents.
 function shoppingListToProto(shoppingList, isFinal) {
     return proto_ShoppingList.create({
         isFinal: isFinal,
@@ -981,8 +984,8 @@ function shoppingListToProto(shoppingList, isFinal) {
         deletedItems: shoppingList.deletedItems.map(shoppingListItemToProto),
     });
 }
-// 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.
+// The mirror of shoppingListItemFromProto. Unscaled model values are scaled again, 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,
@@ -1005,11 +1008,11 @@ function taxToProto(tax) {
 // #endregion
 // #region Entity and item bookkeeping
 // 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.
+// is enough to sort it by entity type. Every blob is versioned by entityETag, tombstones too. The
+// server gives a delete an update number like any other write, 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)
@@ -1021,11 +1024,12 @@ function toCacheWrite(entities) {
     return { blobs: blobs, deletedIds: [] };
 }
 // 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.
+// bigint so that the store's greater-wins rule orders versions correctly. The server assigns an
+// update number to every write, deletes included, so it rises with every change regardless of any
+// clock, 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. A bigint holds it exactly, and a store must compare it as a
+// bigint.
 export function entityETag(updateNumber, updatedAt) {
     if (updateNumber < 0n || updatedAt < 0n)
         throw new InvalidArgumentException("An update number and an updatedAt are never negative");
@@ -1033,10 +1037,10 @@ export function entityETag(updateNumber, updatedAt) {
 }
 // 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.
+// amends, which heldETag carries, so its updatedAt makes it the later copy of that version. If the
+// server sends the amended copy again, that copy 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 that has an
+// update number is versioned by it, as any entity is.
 function messageToBlob(message, heldETag) {
     const entity = getEntity(message.entity);
     const updateNumber = entity.updateNumber !== 0n
@@ -1050,9 +1054,9 @@ function messageToBlob(message, heldETag) {
         bytes: proto_Message.toBinary(message),
     };
 }
-// 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.
+// The messages a container holds that are deleted (isDeleted true) or live (false). A message is
+// deleted according to its update number alone, regardless of its payload. 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) {
@@ -1111,12 +1115,12 @@ function getItemId(item) {
 }
 // #endregion
 // #region Values
-// An absent optional string is null, because Java tells absent from empty
+// An absent optional string is null, because Java distinguishes absent from empty
 function stringFromProto(value) {
     return value === undefined ? null : value;
 }
-// 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.
+// The reverse of stringFromProto. 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;
 }
@@ -1126,9 +1130,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 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.
+// The reverse of addressFromProto, for a delivery address sent directly instead of by id - see
+// buildOrderMessage. id is copied from Address, though it means nothing outside the list the address
+// was read from, and this address is in none.
 function addressToProto(address) {
     return proto_Address.create({
         id: address.id,
@@ -1142,7 +1146,7 @@ function addressToProto(address) {
         countryCode: address.countryCode,
     });
 }
-// The way back, for the addresses of a user sent to the server.
+// The reverse of addressListFromProto, for the addresses of a user sent to the server.
 function addressListToProto(addressList) {
     return proto_AddressList.create({
         defaultAddressId: addressList.defaultAddressId,
@@ -1154,8 +1158,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, so every caller names that of
-// the business the tax is on.
+// The wire carries a tax's raw code, meaningful only within a country, so every caller passes the
+// country of the business the tax is on.
 function taxFromProto(tax, countryCode) {
     return Tax.fromScaledValues(countryCode, tax.taxCode, tax.rate);
 }
@@ -1263,8 +1267,8 @@ function orderFromProto(message, salesOrder, countryCode) {
     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. 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
+// emptied by placing an order and one never created both give null. The rest of the message is set by
+// the server 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;
@@ -1283,6 +1287,6 @@ function takePhotos(attachmentsByOwner, owningEntityId, attachmentBaseUrl) {
 // #endregion
 // The width of the updatedAt an eTag carries below its update number. An int64 is never wider.
 const UPDATED_AT_BITS = 64n;
-// What a blob that is only its eTag holds
+// The bytes of a blob that exists only for its eTag
 const NO_BYTES = new Uint8Array(0);
 const NO_PHOTOS = Object.freeze([]);