@peabody-soft/mbs-model-ts 1.7.0 → 1.8.0

package/dist/Model.js

@@ -13,23 +13,25 @@ import ShoppingList from "./ShoppingList";
 import SyncCache from "./SyncCache";
 import * as SyncKeys from "./SyncKeys";
 import SyncState from "./SyncState";
-// The root of the object model, and all a UI has to be given. Call initialize once, then get the
+// The root of the object model, and the only object a UI needs. Call initialize once, then get the
 // current instance with getInstance.
 //
 // THERE IS NO LOCKING. A caller makes one call at a time and awaits it. Otherwise:
 // - A setBusinessId still reading when signIn reads the business too can publish the anonymous
-//   container's business over the customer's, with no cart or orders. Nothing republishes them.
+//   container's business over the customer's. The published business then has no cart or orders,
+//   and nothing publishes them again.
 // - Two reads at once interleave their pages and writes, as do two tabs on one store (each holds a
 //   Model), so a store supports one tab at a time.
 // A queue inside Model would not fix the tabs, and each public method would need an unqueued twin
 // (signIn calls signOut, businessSyncIn calls updateCart). A caller that calls from several places,
-// like a UI, queues its own calls.
+// like a UI, queues the calls itself.
 class Model {
     constructor() {
         // True when the published business, if any, has been read to the end and found to be the one
-        // _businessId names and to be open. A read's cache-first publish is of what an earlier read left,
-        // and is neither until the read ends. A read that does not end (network failure, a refusal)
-        // leaves it published and unvetted. See readJoinBusinessId, which does not join such a business.
+        // _businessId names and to be open. The cache-first publish of a read holds what an earlier read
+        // stored, which is not known to be either until the read ends. A read that does not end (network
+        // failure, a rejection) leaves the business published and unvetted. See readJoinBusinessId, which
+        // does not join such a business.
         this._isPublishedBusinessVetted = false;
         this._business = new LiveData(null);
         this._profile = new LiveData(null);
@@ -38,7 +40,8 @@ class Model {
         this._authenticationToken = null;
         this._businessId = null;
     }
-    // Sets the service and store to use, and forgets who is signed in and what was being browsed
+    // Sets the service and store to use. Discards the current instance, so nobody is signed in and no
+    // business is browsed.
     static initialize(service, database) {
         Model._service = service;
         Model._cache = new SyncCache(database);
@@ -52,17 +55,17 @@ class Model {
     get business() {
         return this._business;
     }
-    // The customer, their businesses, and the link to each - one LiveData since useful questions
-    // span all three. Null until signed in and loaded.
+    // The customer, their businesses, and the link to each, in one LiveData because a UI usually
+    // needs all three together. Null until signed in and loaded.
     get profile() {
         return this._profile;
     }
     // Signs in and syncs this subject's profile in, for a subject the server has a profile for (use
     // createUser otherwise). Also reads in the business being browsed, if any, as this customer.
     //
-    // Anything thrown after beginSignIn's guard (a bad credential, a refused push while reading the
+    // Anything thrown after beginSignIn's guard (a bad credential, a rejected push while reading the
     // business) calls signOut. profileSyncIn publishes a cached profile before it reaches the
-    // network, so a retry could otherwise find _profile set and trip the "already signed in" guard.
+    // network, so a retry could otherwise find _profile set and fail the "already signed in" guard.
     // Throws NotFoundException if the business being browsed cannot be opened. See businessSyncIn.
     async signIn(authenticationMethod, subjectId, authenticationToken) {
         this.beginSignIn(authenticationMethod, subjectId, authenticationToken);
@@ -80,7 +83,7 @@ class Model {
     // Signs up and creates userToCreate as this subject's profile, for a subject the server has no
     // profile for (use signIn otherwise). Also reads in the business being browsed, if any, as this
     // customer. Throws NotFoundException if that business cannot be opened (see businessSyncIn), after
-    // the User exists. Nothing undoes it: the customer stays signed up and signed in.
+    // the User exists. The sign-up is not undone: the customer stays signed up and signed in.
     async createUser(authenticationMethod, subjectId, authenticationToken, userToCreate) {
         this.beginSignIn(authenticationMethod, subjectId, authenticationToken);
         const authTokens = await this.requireProfileAuthTokens();
@@ -90,9 +93,9 @@ class Model {
     }
     // Updates this customer's own profile with what userProfile holds. Service.updateUser matches the
     // caller against the User by entity id (see ProtoMap.buildUpdateUser), so userProfile must be this
-    // customer's own, read in earlier, not built fresh. Needs a profile already read (see
-    // requireCustomerOfBusiness). Not paged. Publishes nothing today: the response carries no
-    // entities, only reissued tokens (see writeProfileResponse).
+    // customer's own, read in earlier, not built fresh. Throws if no profile has been read. Not
+    // paged. Publishes nothing today: the response carries no entities, only reissued tokens (see
+    // writeProfileResponse).
     async updateUser(userProfile) {
         if (this._profile.value === null)
             throw new IllegalOperationException("Nobody is signed in, so this call cannot be made");
@@ -103,18 +106,18 @@ class Model {
         Model._instance = null;
     }
     // Names the business to browse and reads it in. Publishes null first when replacing a Business,
-    // so the old one is not shown as the one now browsed. A re-read of the current shop does not,
-    // since that would blank the UI and undo syncBusinessContainer's cache-first publish.
+    // so the old one is not shown as the one now browsed. Re-reading the current business does not,
+    // because that would blank the UI and discard syncBusinessContainer's cache-first publish.
     // Throws NotFoundException if the business cannot be opened (see businessSyncIn). What was cached
-    // is published before the network is asked, unless online shopping is off (see publishBusiness),
-    // and is taken back if the read finds the business cannot be opened.
-    // The businessId is held in canonical form (see canonicalizeBusinessId), as the server finds it,
-    // so /WARM-LOAF and /warm-loaf are one storefront, one container and one download. The server
-    // canonicalizes what it is sent.
+    // is published before the network call, unless online shopping is off (see publishBusiness), and
+    // is replaced with null if the read finds the business cannot be opened.
+    // The businessId is held in canonical form (see canonicalizeBusinessId), the form the server finds
+    // a business by, so /WARM-LOAF and /warm-loaf are one storefront, one container and one download.
+    // The server canonicalizes the id it is sent.
     async setBusinessId(businessId) {
-        // An id of only spaces has no canonical form (Java refuses it), so it is held as written. The
-        // server then answers with the NotFoundException a UI shows for a missing business, and this
-        // does not call it a mistake.
+        // An id of only spaces has no canonical form (Java rejects it), so it is held as written. The
+        // server then answers with the NotFoundException a UI shows for a missing business. This method
+        // does not throw for it.
         const canonicalBusinessId = canonicalizeBusinessId(businessId) || businessId;
         const isDifferentBusiness = this._businessId !== canonicalBusinessId;
         this._businessId = canonicalBusinessId;
@@ -126,18 +129,19 @@ class Model {
     //
     // The only writes in this library: this customer's cart at the business being browsed, and an
     // order placed from it. Both need a customer who is a member of the business (see
-    // requireCustomerOfBusiness).
+    // requireCustomerOfBusiness), except that a signed-out visitor can keep a cart locally (see
+    // updateCartLocalOnly).
     // An order reaches the store only after the server accepts it, so a customer never holds an order
-    // the merchant has not heard of, and a failed call leaves nothing to reconcile. A cart is not held
-    // to that (see updateCartLocalOnly).
+    // the server has not accepted, and a failed call leaves nothing to reconcile. A cart can be
+    // stored before the server has it (see updateCartLocalOnly).
     // Creates or replaces this customer's cart, on the server and in the store. An empty list
     // empties the cart, the same state as never having had one.
-    // Signed out, this is updateCartLocalOnly, as the server has no cart for a visitor. Signed in, it
-    // costs a request, so an editor should write each change with updateCartLocalOnly and call this on
-    // its own schedule (debounced, on blur, a timer).
+    // Signed out, this calls updateCartLocalOnly, as the server has no cart for a visitor. Signed in,
+    // it costs a request, so an editor should write each change with updateCartLocalOnly and call this
+    // on a schedule (debounced, on blur, on a timer).
     // A call that matches the stored copy returns without a request (hasShoppingListChanged). It does
-    // not replace reading the business: a push answers with the messages it pushed only, so it brings
-    // back nobody else's changes.
+    // not replace a read of the business: the response to a push holds only the pushed messages, so
+    // it brings no changes made by others.
     async updateCart(shoppingList) {
         if (this._profile.value === null)
             return this.updateCartLocalOnly(shoppingList);
@@ -148,37 +152,38 @@ class Model {
         const partyPreferencesMessage = ProtoMap.buildPartyPreferencesMessage(Ids.getPartyPreferencesMessageId(target.businessLink.id), stored, target.senderId, shoppingList, null, BigInt(Date.now()));
         await this.pushBusinessMessages(target, [partyPreferencesMessage]);
     }
-    // The same, stored locally and not sent. Call it on every edit (a request per tap of a quantity
-    // stepper is not worth making), and updateCart on your own schedule to send.
+    // The same, but stored locally and not sent. Call it on every edit (a request per tap of a
+    // quantity stepper is too many), and call updateCart on a schedule to send.
     // Unsent, nothing is lost: it survives a closed tab, the next updateCart sends it, and createOrder
-    // reads from the store. The cost is that the server, and so this customer's other devices, hear of
+    // reads from the store. The cost is that the server, and so this customer's other devices, receive
     // the change late.
     // A stale sync cannot bring an older server copy back over it: the store versions an amendment at
     // the update number of the copy it amends, buildPartyPreferencesMessage dates it past that copy,
     // and the later copy wins.
     async updateCartLocalOnly(shoppingList) {
-        // No membership to derive a message id from while signed out, so a fresh one is drawn. It
-        // names the cart only for the first edit: buildPartyPreferencesMessage reuses the stored
-        // cart's id, so later edits amend one entity. The sender is ENTITY_ID_NULL for want of a party;
-        // the first push after signing in names the real one.
+        // A signed-out visitor has no membership to derive a message id from, so a fresh id is drawn.
+        // It is the cart's id only for the first edit: buildPartyPreferencesMessage reuses the stored
+        // cart's id, so later edits amend one entity. With no party, the sender is ENTITY_ID_NULL. The
+        // first push after signing in carries the real one.
         if (this._profile.value === null)
             return this.storeCartInCache(ContainerNames.forBusiness(this.requireBusinessBeingBrowsed()), Ids.getNewId(proto_Constants.MESSAGE_ENTITY_TYPE_ID), BigInt(proto_Constants.ENTITY_ID_NULL), shoppingList);
         const target = this.requireCustomerOfBusiness();
         return this.storeCartInCache(target.containerName, Ids.getPartyPreferencesMessageId(target.businessLink.id), target.senderId, shoppingList);
     }
     // Places an order for what is in the cart and empties the cart, as Java
-    // SalesOrderViewModel.saveChanges does on MODE_CREATE. So it takes no shopping list.
-    // The emptied cart is stamped with this fulfillmentMode, which Business.defaultFulfillmentMode
-    // reads back.
-    // The caller mints orderId with Ids.getNewId(Constants.MESSAGE_ENTITY_TYPE_ID), so it can find the
-    // placed order, and can retry a call a NetworkConnectionException left unresolved with the same
-    // id, without placing a second order. getPartyPreferencesMessageId gives a cart the same guarantee.
+    // SalesOrderViewModel.saveChanges does on MODE_CREATE. It takes no shopping list because it reads
+    // the cart from the store.
+    // The emptied cart records this fulfillmentMode, which Business.defaultFulfillmentMode returns.
+    // The caller creates orderId with Ids.getNewId(Constants.MESSAGE_ENTITY_TYPE_ID), so it can find
+    // the placed order, and can retry a call that a NetworkConnectionException left unresolved using
+    // the same id, without placing a second order. getPartyPreferencesMessageId gives a cart the same
+    // guarantee.
     // A delivery must name an address: an id from this customer's list, or a full address sent
     // directly (see requireDeliveryAddress).
     async createOrder(orderId, fulfillmentMode, deliveryAddressId, deliveryAddress, note) {
         const target = this.requireCustomerOfBusiness();
-        // Read from the store, not the published Business, so the order reflects the cart as stored,
-        // not a value an observer may still hold
+        // Read from the store rather than the published Business, so the order matches the stored cart
+        // and not a copy an observer may hold
         const partyPreferencesMessage = await Model.getCache().readPartyPreferences(target.containerName);
         const shoppingList = partyPreferencesMessage === null
             ? ShoppingList.EMPTY
@@ -186,7 +191,7 @@ class Model {
         if (shoppingList.existingItems.length === 0)
             throw new IllegalOperationException("The cart holds nothing, so there is no order to place");
         Model.requireDeliveryAddress(target.addresses, fulfillmentMode, deliveryAddressId, deliveryAddress);
-        // One time for both messages, which is when the order was placed
+        // One timestamp for both messages: the time the order was placed
         const now = BigInt(Date.now());
         // One request for the order and the emptied cart: two calls could leave an order placed and the
         // cart still full if the second failed
@@ -207,12 +212,12 @@ class Model {
         this._authenticationToken = authenticationToken;
     }
     // #region Pushing
-    // One push, plus everything that follows the server accepting it. The messages go out in one
-    // request with how far this business container's reads have got. The server answers with these
-    // messages under their assigned update numbers and nothing more: a push is not a read. They are
-    // stored and move no cursor, so the next read receives them again, with anything somebody else
-    // changed in the meantime. A refused push fails the call itself, like any Service call on a bad
-    // status, so reaching the write below means the server took it.
+    // Pushes the messages in one request, together with the update number this business container's
+    // reads have reached, then stores the response. The server answers with these messages under their
+    // assigned update numbers and nothing else: a push is not a read. They are stored without moving
+    // any cursor, so the next read receives them again, along with anything others changed in the
+    // meantime. A rejected push throws from the Service call itself, as for any bad status, so
+    // reaching the write below means the server accepted it.
     async pushBusinessMessages(target, messages) {
         const cache = Model.getCache();
         const messageUpdateNumber = await cache.readMessageUpdateNumber(target.containerName);
@@ -227,9 +232,7 @@ class Model {
             this.publishBusiness(await cache.readBusiness(target.containerName));
     }
     // Amends the cart containerName holds and writes the result to the cache. Nothing is pushed.
-    // The two paths of updateCartLocalOnly differ in container, id and sender: a visitor's has a
-    // freshly drawn id and no sender, a customer's has the id their membership derives and their own
-    // sender id.
+    // The two callers differ in container, id and sender: see updateCartLocalOnly.
     async storeCartInCache(containerName, messageId, senderId, shoppingList) {
         const cache = Model.getCache();
         const changeCount = await cache.writePartyPreferences(containerName, ProtoMap.buildPartyPreferencesMessage(messageId, await cache.readPartyPreferences(containerName), senderId, shoppingList, null, BigInt(Date.now())));
@@ -249,7 +252,8 @@ class Model {
     }
     // Everything a write needs, gathered before anything is built. Each missing precondition throws
     // its own error: no business browsed, business not loaded, no profile loaded, or a customer who
-    // is not a member. The server would refuse the last anyway, with no link token to sign with.
+    // is not a member. The server would reject the last anyway, since there is no link token to sign
+    // with.
     requireCustomerOfBusiness() {
         const businessId = this.requireBusinessBeingBrowsed();
         const business = this._business.value;
@@ -270,13 +274,13 @@ class Model {
     }
     // Checks where an order is delivered: an id in this customer's address list (the list
     // Order.deliveryAddressId resolves against) or a full address sent directly. An id not in the
-    // list would leave the business with an order it cannot read, so it is refused here. A full
+    // list would leave the business with an order it cannot read, so it is rejected here. A full
     // address needs no check against the list.
     static requireDeliveryAddress(addresses, fulfillmentMode, deliveryAddressId, deliveryAddress) {
         if (deliveryAddress !== null)
             return;
         if (deliveryAddressId === BigInt(proto_Constants.ENTITY_ID_NULL)) {
-            // Pick-up names neither, which is normal. See Order.deliveryAddressId
+            // A pick-up has neither, which is normal. See Order.deliveryAddressId
             if (fulfillmentMode === proto_FulfillmentMode.DELIVERY)
                 throw new InvalidArgumentException("An order to be delivered has to name a delivery address");
             return;
@@ -287,19 +291,20 @@ class Model {
     // #endregion
     // #region The four calls of Service, each as this model makes it
     //
-    // Each pages, caches every page as it arrives, files what the server issued, and publishes what
-    // the cache then holds.
+    // Each caches the response (a read caches every page as it arrives), files the tokens the server
+    // issued, and publishes what the cache then holds. A read is paged. A sign up and an update are not.
     // Reads in the business being browsed: an anonymous visitor under its businessId, a signed-in
     // customer under their own container (see getBusinessContainerName), joining as a customer first
     // if not linked (see requireBusinessLink).
     // Throws NotFoundException when the business cannot be opened, on a first read or a later one (a
-    // business can stop being open after it was cached). The server says so when it does not exist,
-    // is deleted, or does not allow customers to join. Online shopping off is decided here (see
-    // syncBusinessContainer). Having nothing to buy does not: that business is open, with an empty
-    // catalog. The cache is kept, except that a business that is no longer the one the businessId
-    // names is replaced by the one that is.
-    // isStartedOver marks the one self-call, when the link the profile found for the businessId is of
-    // a business that no longer has it. The profile is read again and this starts over from it.
+    // business can stop being open after it was cached). The server throws it when the business does
+    // not exist, is deleted, or does not allow customers to join. This method throws it too when
+    // online shopping is off (see syncBusinessContainer). A business with nothing to buy is open,
+    // with an empty catalog. The cache is kept, unless it holds a business other than the one the
+    // businessId now names, which is replaced.
+    // isStartedOver is true on the single recursive call. That call happens when the profile's link
+    // for the businessId belongs to a business that no longer has it: the profile is read again and
+    // this method starts over.
     async businessSyncIn(isStartedOver = false) {
         const businessId = this._businessId;
         if (businessId === null || businessId.length === 0)
@@ -336,11 +341,11 @@ class Model {
         const authTokens = await this.requireBusinessAuthTokens(containerName, link);
         // The link names the business by entity id, because the link token that signs this call is for it
         const isBusinessNamed = await this.syncBusinessContainer(containerName, businessId, link.businessId, ProtoMap.buildAuthTokens(authTokens));
-        // The link's business has another businessId now, which the profile that found the link by this
-        // one did not know. The container is given up, so the profile is read again: the link is then
-        // found by this businessId or not, and a businessId naming another business is joined. Only
-        // once: a re-read profile that still finds the same link for the same businessId means the
-        // server contradicts itself
+        // The link's business has a different businessId than the profile knew when it found the link
+        // by this one. The container is discarded and the profile is read again. The link is then found
+        // by this businessId or not, and if the businessId names another business, that business is
+        // joined. This happens only once: if a re-read profile still finds the same link for the same
+        // businessId, the server contradicts itself
         if (!isBusinessNamed) {
             if (isStartedOver)
                 throw new InternalServerException(`The business that the link for the businessId ${businessId} is of does not have it, though the profile was read again`);
@@ -354,8 +359,8 @@ class Model {
             return;
         // The visitor's cart holds taxes as raw codes, meaningful only within the country of the
         // business it was built in. That country is read from the anonymous container. A cart is stored
-        // only after its business has been (see updateCartLocalOnly); failing that, the business being
-        // browsed is the same one.
+        // only after its business has been read (see updateCartLocalOnly), so the container normally
+        // has the country. If it has none, the business being browsed is the same business.
         const anonymousCountryCode = ProtoMap.getBusinessResponseCountryCode(anonymous) ?? this._business.value?.countryCode;
         if (anonymousCountryCode === undefined)
             throw new IllegalOperationException("The business the visitor's cart was built in is not known, so its taxes cannot be read");
@@ -375,28 +380,27 @@ class Model {
     async syncAnonymousBusiness(businessId) {
         await this.syncBusinessContainer(ContainerNames.forBusiness(businessId), businessId, null, null);
     }
-    // Reads one business into containerName, cache first: what is held publishes before the network
-    // is touched, so a returning customer sees the shop at once. Cursors start where earlier reads got
-    // to (see SyncCache.readBusinessCursors), so a repeat call asks only what changed.
+    // Reads one business into containerName, cache first: the cached business is published before any
+    // network call, so a returning customer sees the shop at once. Cursors start where earlier reads
+    // got to (see SyncCache.readBusinessCursors), so a repeat call requests only what changed.
     // The first request names the business by entity id where known (businessEntityId from a link,
     // else the one in the container), else by businessId, and every later page does the same.
-    // firstAuthTokens are the link's and sign the reads by entity id. A read by businessId is signed
-    // with nothing.
+    // firstAuthTokens are the link's and sign the reads by entity id. A read by businessId is sent
+    // with no tokens.
     //
     // Whether the business can be opened is decided from the container once every page is written,
     // since a page carries only what changed. After every read, in order:
     // 1. The container holds the business businessId names. A business keeps its entity id when its
     //    businessId changes and another can take the old one, so a container read by entity id may
-    //    hold the wrong business. It is given up and read again from the start by businessId, once,
+    //    hold the wrong business. It is discarded and read again from the start by businessId, once,
     //    which finds the right business or none (NotFoundException from the server).
-    //    A read named by a link cannot be redone that way (a link token is refused with a
-    //    businessId). Its container is given up and this answers false, so the caller starts again
-    //    from a re-read profile (see businessSyncIn). Otherwise this answers true.
+    //    A read named by a link cannot be redone that way (a link token is rejected with a
+    //    businessId). Its container is discarded and this returns false, so the caller starts again
+    //    from a re-read profile (see businessSyncIn). Otherwise this returns true.
     // 2. Online shopping is on in the general settings (no settings means off). The server does not
-    //    refuse a business for this, so this throws NotFoundException.
-    // Nothing more is asked of a business. One with nothing a customer can buy (no product that is
-    // enabled, not sold only offline, and has a priced package) is open: it is published with an empty
-    // catalog, and a UI tells its customers there is nothing to buy.
+    //    reject a business for this, so this throws NotFoundException.
+    // A business with nothing to buy (no enabled product that is sold online and has a priced
+    // package) is open, and is published with an empty catalog.
     async syncBusinessContainer(containerName, businessId, businessEntityId, firstAuthTokens) {
         const cache = Model.getCache();
         const cached = await cache.readBusiness(containerName);
@@ -407,14 +411,15 @@ class Model {
         // does. It may not be what the businessId finds now: a business can give up its businessId to
         // another, or change it.
         const cachedEntityId = ProtoMap.getBusinessResponseBusinessEntityId(cached);
-        // What the store accepted (the blobs it stored). Decides the publish at the end.
+        // How much the store accepted: blobs stored plus ids deleted, as in the Publishing region.
+        // Decides the publish at the end.
         let changeCount;
         try {
             changeCount = await this.readBusinessPages(containerName, businessEntityId ?? cachedEntityId ?? businessId, await cache.readBusinessCursors(containerName), ProtoMap.getBusinessResponseAttachmentBaseUrlExpiry(cached), firstAuthTokens);
         }
         catch (error) {
-            // The server says the business cannot be opened, so what was published from the cache is not
-            // what is there. The container is left as it is: deciding that a business is gone is the caller's
+            // The server says the business cannot be opened, so the business published from the cache is
+            // out of date. The container is left as it is, because the caller decides whether the business is gone
             if (error instanceof NotFoundException)
                 this.publishBusiness(null);
             throw error;
@@ -422,14 +427,15 @@ class Model {
         let held = await cache.readBusiness(containerName);
         // Whether what was published is no longer what the container holds
         let isPublishedStale = changeCount !== 0;
-        // Named by the cached entity id, not by a link, which names only its own business
+        // For a read named by the cached entity id. A link names only its own business, so a read named
+        // by a link is handled below
         if (businessEntityId === null && cachedEntityId !== null && !Model.isBusinessNamed(held, businessId)) {
-            // Nothing read of one business says anything about another, so none of the container is kept,
-            // nor how far it was read. The business the businessId names is read from the beginning, with
-            // no attachment url held: the expiry is zero, not the container's, because the url it held
-            // was the old business's and went with it. A server sent that expiry would take the new
-            // business to have the url and send none, leaving every photo without one. Signed with
-            // nothing, as a link token is refused with a businessId
+            // Nothing read from one business applies to another, so the whole container is discarded,
+            // along with its cursors. The business the businessId names is read from the beginning, with
+            // an attachment url expiry of zero instead of the container's, because the url the container
+            // held belonged to the old business and is gone. If the server were sent the container's
+            // expiry, it would take the new business to have the url and send none, leaving every photo
+            // without one. The read is sent with no tokens, as a link token is rejected with a businessId
             await cache.deleteBusiness(containerName);
             this.publishBusiness(null);
             await this.readBusinessPages(containerName, businessId, new SyncState(SyncKeys.BUSINESS_SYNC_IN), 0n, null);
@@ -439,27 +445,25 @@ class Model {
         // The businessId finds the business that has it, so any other is the server contradicting itself
         if (businessEntityId === null && !Model.isBusinessNamed(held, businessId))
             throw new InternalServerException(`The business that was read for the businessId ${businessId} has the businessId ${ProtoMap.getBusinessResponseBusinessId(held)}`);
-        // Named by a link whose business no longer has the businessId. It cannot be re-read by
-        // businessId (a link token is refused with one), so the container is given up as above and the
-        // caller starts again
+        // For a read named by a link whose business no longer has the businessId. It cannot be re-read
+        // by businessId (a link token is rejected with one), so the container is discarded as above and
+        // the caller starts again
         if (businessEntityId !== null && !Model.isBusinessNamed(held, businessId)) {
             await cache.deleteBusiness(containerName);
             this.publishBusiness(null);
             return false;
         }
-        // A container holding no business says nothing about online shopping. That is a failure of its
-        // own, not a business with it off (see readJoinBusinessId)
+        // A container with no business has no online shopping setting to check. A read that ends with no
+        // business is a server failure, not a business with online shopping off (see readJoinBusinessId)
         if (ProtoMap.getBusinessResponseBusinessEntityId(held) !== null && !ProtoMap.isBusinessResponseOnlineShoppingOn(held)) {
-            // What was published from the cache is the business as it was when open, not as it is now.
-            // Nothing of a business that cannot be opened stays published, or a customer could be joined
-            // to it (see readJoinBusinessId)
+            // What was published from the cache is the business as it was when open. A business that
+            // cannot be opened must not stay published, or a customer could be joined to it (see
+            // readJoinBusinessId)
             this.publishBusiness(null);
             throw new NotFoundException("The business has not turned online shopping on");
         }
-        // A read the store took nothing from re-renders nobody: the cache was published above, and
-        // nothing here changes what a later read answers.
-        // A business with nothing a customer can buy is published like any other. It is open, and says
-        // so with an empty catalog (Catalog.productCount), which a UI words for its customers.
+        // Publish what the container now holds if it changed during the read. Otherwise the cache
+        // published at the start is still current.
         if (isPublishedStale)
             this.publishBusiness(held);
         // What is published now was read to the end, is the business the businessId names, and is open
@@ -467,10 +471,10 @@ class Model {
         return true;
     }
     // Reads every page the server has for the given cursors and writes each into the container as it
-    // arrives. The business is named by entity id or businessId, decided by the first request, and
-    // every later page names it the same way. Answers what the store accepted (the blobs it stored).
-    // firstAuthTokens are those of a link. A link token is refused with a businessId, so a read
-    // naming the business by it is sent none, even if given some.
+    // arrives. The first request names the business by entity id or by businessId, and every later
+    // page names it the same way. Returns how much the store accepted: blobs stored plus ids deleted,
+    // summed over the pages. firstAuthTokens are those of a link. A link token is rejected with a
+    // businessId, so a read that names the business by it sends no tokens, even if given some.
     async readBusinessPages(containerName, business, cursors, attachmentBaseUrlExpiry, firstAuthTokens) {
         const cache = Model.getCache();
         let request = ProtoMap.buildBusinessSyncOutRequest(business, cursors, attachmentBaseUrlExpiry);
@@ -488,30 +492,28 @@ class Model {
             const next = ProtoMap.nextBusinessSyncOutRequest(request, page);
             if (next === null)
                 return changeCount;
-            // The next page asks from where this one got to, signed with any token this one reissued
+            // The next request continues from where this page ended, signed with any token this page reissued
             request = next;
             authTokens = ProtoMap.refreshAuthTokens(authTokens, issued);
         }
     }
-    // True when the response holds the business businessId names, or no business, which says nothing
-    // against it. Only a business with another businessId is another business. Ids are compared as
-    // the server finds them, ignoring case and spacing (see canonicalizeBusinessId)
+    // True when the response holds the business businessId names, or holds no business, which does
+    // not contradict it. Ids are compared as the server finds them, ignoring case and spacing (see
+    // canonicalizeBusinessId)
     static isBusinessNamed(response, businessId) {
         const heldBusinessId = ProtoMap.getBusinessResponseBusinessId(response);
         return (heldBusinessId === null ||
             canonicalizeBusinessId(heldBusinessId) === canonicalizeBusinessId(businessId));
     }
     // The BusinessLink of this profile for the business, joining as a customer first (once) if not
-    // linked. A business in the profile with no matching link is a server inconsistency a join would
-    // not fix, so that throws.
+    // linked. The profile can hold the business without a link to it: the link of a membership that
+    // ended is deleted and the business stays. The join then makes a new link.
     async requireBusinessLink(businessId, profile) {
         if (profile.user === null)
             throw new IllegalOperationException("No profile has been read, so who is browsing is not known");
         const link = Model.findBusinessLink(profile, businessId);
         if (link !== null)
             return link;
-        if (Model.findBusinessEntity(profile, businessId) !== null)
-            throw new InternalServerException(`This customer has no BusinessLink to business ${businessId}`);
         const joinBusinessId = await this.readJoinBusinessId(businessId);
         await this.profileSyncIn(ProtoMap.buildProfileSyncOutRequest(await Model.getCache().readProfileCursors(this.requireProfileContainerName()), joinBusinessId), await this.requireProfileAuthTokens());
         // Tried once: a join that leaves no link is the server contradicting itself, and retrying
@@ -532,7 +534,7 @@ class Model {
             return alreadyHeld.id;
         await this.syncAnonymousBusiness(businessId);
         // A missing business is a NotFoundException from the read above. Reaching here with none
-        // published means the server answered with no Business, a failure of its own
+        // published means the server answered with no Business, which is a server failure
         const business = this._business.value;
         if (business === null)
             throw new InternalServerException(`The read of business ${businessId} answered with no Business`);
@@ -567,9 +569,10 @@ class Model {
     // The credentials that sign a call about a customer's business container. The authentication
     // token comes from memory, as in buildProfileAuthTokens: a stored AuthTokens does not keep it.
     // The user token and link token are read separately: storeIssuedTokens overwrites the whole blob
-    // per call, so relying on it alone would lose whichever token the last call did not reissue. Each
-    // falls back to its own source: the profile container's user token, and this link's linkToken. A
-    // fresh membership has no issued tokens, so the write below seeds this container with them.
+    // per call, so relying on it alone would lose any token the last call did not reissue. A token
+    // not stored here comes from another source: the user token from the profile container, and the
+    // link token from the link. A fresh membership has no issued tokens, so the write below seeds
+    // this container with them.
     // A link with no linkToken is a server inconsistency, and throws rather than sending unsigned.
     async requireBusinessAuthTokens(containerName, link) {
         const authenticationMethod = this._authenticationMethod;
@@ -591,9 +594,9 @@ class Model {
             await cache.writeAuthTokens(containerName, authTokens);
         return authTokens;
     }
-    // The profile of whoever is signed in, paged like a business read. What it earns files in the
-    // profile container. The call is about the caller alone, so its AuthTokens carries no link
-    // token. A linkToken travels only inside a BusinessLink, stored with the profile.
+    // Reads the profile of whoever is signed in, paged like a business read. The tokens it receives
+    // are stored in the profile container. The call is about the caller alone, so its AuthTokens has
+    // no link token. A linkToken travels only inside a BusinessLink, stored with the profile.
     async profileSyncIn(firstRequest, firstAuthTokens) {
         const containerName = this.getProfileContainerName();
         if (containerName === null)
@@ -620,7 +623,7 @@ class Model {
                 break;
             request = next;
             // Each call after the first is signed with what the previous page reissued, since a token can
-            // fall due part way through a long read
+            // expire part way through a long read
             authTokens = ProtoMap.refreshAuthTokens(authTokens, ProtoMap.getResponseAuthTokens(page));
         }
         // As above: nothing the store took, nothing published
@@ -629,8 +632,8 @@ class Model {
             response = await Model.getCache().readProfile(containerName);
             this.publishProfile(response);
         }
-        // Last, so everything that arrived is cached and published first. The pages were not at fault,
-        // the join was
+        // Checked last, so everything that arrived is cached and published before this can throw. The
+        // pages are valid even when the join is not.
         Model.requireJoinedBusiness(joinBusinessId, hasJoinedLink, hasJoinedBusiness);
         return response;
     }
@@ -653,11 +656,11 @@ class Model {
     // Without both, the caller is a customer of something it cannot reach. Shared by the two calls
     // that can carry a joinBusinessId.
     //
-    // A ServiceException, not a caller error: the server answered 200 and left out what was asked
-    // for. 500 says retrying is worth it.
+    // Throws a ServiceException, since the fault is the server's and not the caller's: the server
+    // answered 200 and left out what was asked for. The 500 status means a retry is worthwhile.
     // Only a joinBusinessId the server could act on is checked (Java Business.isValidBusinessId,
-    // which Constants.ENTITY_ID_NULL also fails, so "no join asked" needs no case). The server refuses
-    // any other (400), which fails the call itself.
+    // which Constants.ENTITY_ID_NULL also fails, so "no join asked" needs no case). The server rejects
+    // any other with a 400, which fails the call itself.
     static requireJoinedBusiness(joinBusinessId, hasBusinessLink, hasBusiness) {
         if (Ids.getEntityTypeId(joinBusinessId) !== proto_Constants.BUSINESS_ENTITY_TYPE_ID)
             return;
@@ -670,11 +673,11 @@ class Model {
                 : "BusinessLink";
         throw new InternalServerException(`A join of business ${joinBusinessId} was answered with no ${missing}`);
     }
-    // What every profile response leaves in the store: its entities cached, and what it reissued
-    // filed against the same container. Answers how much the store took, which decides whether
-    // anything is published. Shared by the three calls that receive one (a page of a read, a sign up,
-    // an update) so they cache and file tokens the same way. It does not publish: a read publishes
-    // once for a whole loop of these, the other two once each.
+    // Caches the entities of a profile response and files the tokens it reissued under the same
+    // container. Returns how much the store accepted, which decides whether anything is published.
+    // The three calls that receive a profile response (a page of a read, a sign up, an update) share
+    // this, so they cache and file tokens the same way. It does not publish: a read publishes once
+    // after all its pages, the other two once each.
     // Only a page of a read moves the container's cursors. A sign up and an update are changes this
     // client made and the next read brings them back, so they are stored without moving any.
     async cacheProfileResponse(containerName, response, isPageOfRead) {
@@ -685,11 +688,11 @@ class Model {
         await this.storeIssuedTokens(ProtoMap.getResponseAuthTokens(response), containerName);
         return changeCount;
     }
-    // What a profile call other than a read leaves behind: the response cached and published, as for
-    // a paged read without the paging. A sign up and an update publish by the rule a read follows,
-    // on what the store took. An update publishes nothing today because the server puts no entities
-    // in its response, only what it reissued. If it ever answers with the stored User, whose update
-    // number and updated time a caller cannot know, this publishes it unchanged.
+    // Handles the response of a profile call other than a read: caches and publishes it, as for a
+    // paged read without the paging. Like a read, a sign up and an update publish only when the store
+    // accepted something. An update publishes nothing today because the server puts no entities in
+    // its response, only reissued tokens. If it ever answers with the stored User, whose update
+    // number and updated time a caller cannot know, this publishes it as the server sent it.
     async writeProfileResponse(response) {
         const containerName = this.getProfileContainerName();
         if (containerName === null)
@@ -698,14 +701,14 @@ class Model {
             this.publishProfile(await Model.getCache().readProfile(containerName));
         return response;
     }
-    // Files what a call earned against the container the call was about: a profile call's tokens in
-    // the subject's profile container, a business call's in that business's container. The call
-    // decides this, since a token says nothing about what it is for. A business sync out that
-    // reissues a user token still files that copy with the business it came from.
+    // Stores the tokens a call received in the container the call was about: a profile call's tokens
+    // in the subject's profile container, a business call's in that business's container. The caller
+    // picks the container, because a token does not record what it is for. A business sync out that
+    // reissues a user token stores that copy with the business it came from.
     // A profile call carries no link token here: a membership's link token travels inside its
     // BusinessLink, stored with the profile.
-    // A failed write is swallowed: the server issues another next call, so losing one costs a round
-    // trip, and surfacing it would turn a working read into a thrown one.
+    // A failed write is swallowed: the server issues new tokens on the next call, so a lost one is
+    // replaced, and throwing would turn a successful read into a failed one.
     async storeIssuedTokens(issued, containerName) {
         if (issued === undefined)
             return;
@@ -719,8 +722,9 @@ class Model {
     // #endregion
     // #region Containers and credentials
     // Where this subject's profile and tokens are cached. Keyed by authentication method and subject
-    // id, since two identity providers could issue the same subject id. Null when signed out. Several
-    // can coexist, so signing back in finds the subject's own profile.
+    // id, since two identity providers could issue the same subject id. Null when signed out.
+    // Containers for several subjects can coexist, so signing back in finds that subject's own
+    // profile.
     getProfileContainerName() {
         return this._authenticationMethod === null || this._subjectId === null
             ? null
@@ -757,16 +761,16 @@ class Model {
     // #endregion
     // #region Publishing
     //
-    // A read publishes on how much the store accepted (blobs stored plus ids deleted, summed over
-    // every page), not on what the response carried. The store keeps a blob only when its eTag is
-    // later, so a response can be rejected in full (a cursor that moved without its eTag resends an
-    // entity already cached). Publishing that would re-render every observer over an identical value.
+    // A read publishes only when the store accepted something (blobs stored plus ids deleted, summed
+    // over every page), whatever the response carried. The store keeps a blob only when its eTag is
+    // later, so it can reject a response in full (a cursor that moved without its eTag resends an
+    // entity already cached). Publishing then would notify every observer of an identical value.
     // All four calls follow this, so an update publishes nothing (see writeProfileResponse).
     //
     // A business with online shopping off is not published, even from the cache, or a customer could
     // be joined to it. A read that finds the published business is no longer open, or that the server
-    // refuses, takes it back by publishing none. What came from the cache counts as open only once the
-    // read has ended (see _isPublishedBusinessVetted, which readJoinBusinessId goes by).
+    // rejects, publishes null in its place. A business published from the cache counts as open only
+    // once the read has ended (see _isPublishedBusinessVetted, which readJoinBusinessId checks).
     publishBusiness(response) {
         this.publish(Model.buildPublishable(response));
     }