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

package/dist/Model.js

@@ -13,23 +13,23 @@ import ShoppingList from "./ShoppingList";
 import SyncCache from "./SyncCache";
 import * as SyncKeys from "./SyncKeys";
 import SyncState from "./SyncState";
-// The root of the object model, and the only thing a UI has to be given. Call initialize once,
-// then always fetch the current instance via getInstance.
+// The root of the object model, and all a UI has to be given. Call initialize once, then get the
+// current instance with getInstance.
 //
-// THERE IS NO LOCKING, and nothing here makes one call wait for another: a caller makes one call at a time, and awaits it. A
-// setBusinessId that is still reading when signIn reads the business too can publish the business of the anonymous container
-// over the one the customer's link names, with no cart and no orders, and nothing republishes them; two reads at once
-// interleave their pages and their writes. And a store has one tab using it at a time: two tabs on one store each hold a Model
-// of their own, and one tab's deleteBusiness and read again can interleave with the pages another is writing.
-// A queue inside Model would settle the first and not the second, and would not be a small one: signIn calls signOut and
-// businessSyncIn calls updateCart, so each public method would need a twin that does not queue, for these to call. A caller
-// that calls from several places - a UI - queues its calls itself.
+// 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.
+// - 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.
 class Model {
     constructor() {
-        // Whether the business that is published, if one is, is one that a read has been through to the end and found to be the
-        // one that _businessId names and to be open. The cache-first publish of a read is of what an earlier read left, and is
-        // neither of those until the read ends - a read that does not end (the network failing, or a refusal) leaves it published
-        // and unvetted. See readJoinBusinessId, which does not take such a business to join.
+        // 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.
         this._isPublishedBusinessVetted = false;
         this._business = new LiveData(null);
         this._profile = new LiveData(null);
@@ -44,7 +44,7 @@ class Model {
         Model._cache = new SyncCache(database);
         Model._instance = null;
     }
-    // The model as it is now. Ask for it every time; never keep it - see the note on this class.
+    // The current model. Fetch it each time and do not keep it: signOut discards it.
     static getInstance() {
         return Model._instance ?? (Model._instance = new Model());
     }
@@ -57,17 +57,13 @@ class Model {
     get profile() {
         return this._profile;
     }
-    // Signs in with the given credentials and syncs this subject's profile in - for a subject the
-    // server already has a profile for; createUser is what a subject with none yet uses instead. Also
-    // reads in the business being browsed, if any, now signed in as this customer.
+    // 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.
     //
-    // Idempotent on failure: beginSignIn's own "already signed in" guard aside, anything that throws
-    // after it - a bad credential, a refused push while reading in the business being browsed -
-    // discards this instance via signOut rather than leaving it half signed in. profileSyncIn
-    // publishes a cached profile before it ever reaches the network, so without this, a retry after
-    // such a failure could find _profile already set and trip that same guard despite never having
-    // actually signed in.
-    // Throws NotFoundException if the business being browsed cannot be opened - see businessSyncIn.
+    // Anything thrown after beginSignIn's guard (a bad credential, a refused 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.
+    // Throws NotFoundException if the business being browsed cannot be opened. See businessSyncIn.
     async signIn(authenticationMethod, subjectId, authenticationToken) {
         this.beginSignIn(authenticationMethod, subjectId, authenticationToken);
         try {
@@ -81,12 +77,10 @@ class Model {
             throw error;
         }
     }
-    // Signs up with the given credentials, creating userToCreate as this subject's profile - for a
-    // subject the server has no profile for yet; signIn is what an already known subject uses instead.
-    // Also reads in the business being browsed, if any, now signed in as this customer.
-    // Throws NotFoundException if the business being browsed cannot be opened - see businessSyncIn. That is
-    // after the User has been created, and nothing undoes it: the customer stays signed up, and signed in, with
-    // a profile held, whatever the read of the business answered.
+    // 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.
     async createUser(authenticationMethod, subjectId, authenticationToken, userToCreate) {
         this.beginSignIn(authenticationMethod, subjectId, authenticationToken);
         const authTokens = await this.requireProfileAuthTokens();
@@ -94,38 +88,33 @@ class Model {
         if (this._businessId !== null)
             await this.businessSyncIn();
     }
-    // Updates this customer's own profile with what userProfile now holds. Service.updateUser matches
-    // the caller against the User it is sent by entity id - see ProtoMap.buildUpdateUser - so
-    // userProfile must be this customer's own, previously read in rather than built fresh.
-    // Requires a profile already read, the same "signed in" a business write needs of its profile half
-    // - see requireCustomerOfBusiness. Not paged, and today publishes nothing: its response carries no
-    // entities, only whatever the server reissued - see writeProfileResponse.
+    // 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).
     async updateUser(userProfile) {
         if (this._profile.value === null)
             throw new IllegalOperationException("Nobody is signed in, so this call cannot be made");
         await this.writeProfileResponse(await Model.getService().updateUser(ProtoMap.buildUpdateUser(userProfile), await this.requireProfileAuthTokens()));
     }
-    // Discards this model outright: the next getInstance() builds a fresh one, signed out and
-    // browsing nothing.
+    // Discards this model. The next getInstance() builds a fresh one, signed out and browsing nothing.
     async signOut() {
         Model._instance = null;
     }
-    // Names the business to browse and reads it in, publishing null first so a Business being
-    // replaced is never shown as the one now being browsed - but only when it IS being replaced.
-    // This is also how a caller re-reads the shop it is already on, and nulling unconditionally
-    // would blank the UI for the length of the read and undo syncBusinessContainer's own
-    // cache-first publish two lines later.
-    // Throws NotFoundException if the business cannot be opened - see businessSyncIn. Whatever was cached
-    // is published before the network is asked, unless it is a business that has not turned online shopping
-    // on - see publishBusiness - and is taken back, by publishing none, if the read then finds that the business
-    // cannot be opened.
-    // The businessId is held and used as the server finds a business by it, in lower case and without the spaces round it
-    // (see canonicalizeBusinessId): a url is typed in any case, and /WARM-LOAF and /warm-loaf are one storefront, so, they are
-    // one container, one download, and not a different business to be shown as none first. What is sent to the server is that
-    // form too, which it makes of whatever it is sent, so nothing is lost by it.
+    // 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.
+    // 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.
     async setBusinessId(businessId) {
-        // An id of nothing but spaces has no canonical form - Java refuses it - and is held as it was written: it is the server that
-        // says there is no such business, with the NotFoundException that a UI shows for one, and not this that calls it a mistake
+        // 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.
         const canonicalBusinessId = canonicalizeBusinessId(businessId) || businessId;
         const isDifferentBusiness = this._businessId !== canonicalBusinessId;
         this._businessId = canonicalBusinessId;
@@ -136,22 +125,19 @@ class Model {
     // #region What a customer writes
     //
     // The only writes in this library: this customer's cart at the business being browsed, and an
-    // order placed from it. An order pushes to the server and touches the store only once the server
-    // accepts, so a failed call leaves nothing to reconcile and a caller just retries: an order
-    // stored here that the server never saw would be one a customer believes they placed and a
-    // merchant has never heard of. A cart is not held to that, and updateCartLocalOnly is the whole
-    // of the difference.
-    // Both need this customer to be a member of the business being browsed - three separate things
-    // to be missing, so three separate failures; see requireCustomerOfBusiness.
-    // Creates or replaces this customer's cart, on the server and in the store both. An empty list
-    // empties the cart - the same state as never having had one.
-    // Signed out, this is just updateCartLocalOnly - there is no server cart yet for a visitor the
-    // server has not heard of. Signed in, it costs a request, so an editor should write every change
-    // with updateCartLocalOnly and call this on its own schedule (debounced, on blur, a timer).
-    // Safe to call often: hasShoppingListChanged checks against the store's own copy rather than
-    // whatever the caller last sent, so a call that matches what is already there returns without a
-    // request. Not a substitute for reading the business, though - a push answers with the messages it
-    // pushed and nothing else, and a call that does not go out brings no change of anybody else's back.
+    // order placed from it. Both need a customer who is a member of the business (see
+    // requireCustomerOfBusiness).
+    // 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).
+    // 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).
+    // 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.
     async updateCart(shoppingList) {
         if (this._profile.value === null)
             return this.updateCartLocalOnly(shoppingList);
@@ -162,42 +148,37 @@ 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 this on every edit - a request per tap of a
-    // quantity stepper is not worth making - then call updateCart on your own schedule (debounced,
-    // on blur, before signing in) to actually send it.
-    // Nothing is lost by leaving it unsent: it survives a closed tab, the next updateCart sends it,
-    // and createOrder reads straight from the store. All a caller gives up is that the server, and so
-    // this customer's other devices, hear about the change late.
-    // It also cannot be undone by a stale sync in bringing an older server copy back: the store
-    // versions an amendment at the update number of the copy it amends, where the later copy wins, and
-    // buildPartyPreferencesMessage always dates an amendment past what it replaces.
+    // 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.
+    // 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
+    // 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 one is drawn instead - once,
-        // and only once: buildPartyPreferencesMessage keeps amending the same entity by reusing its id,
-        // so a second edit cannot leave two behind. The sender is ENTITY_ID_NULL for want of a party;
+        // 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.
         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 it - the list is used up becoming the
-    // order, as Java SalesOrderViewModel.saveChanges does on MODE_CREATE. Takes no shopping list
-    // itself for that reason: the cart is the order.
-    // The emptied party preferences message is also stamped with this fulfillmentMode, so it becomes
-    // this order's rather than whatever the cart last held - see Business.defaultFulfillmentMode,
-    // which is what reads it back.
-    // orderId is the caller's to mint, with Ids.getNewId(Constants.MESSAGE_ENTITY_TYPE_ID) - not
-    // minted here - so that a caller holds it before the call is made: to find the order once placed
-    // without a server-assigned id to wait for, and to retry a call a NetworkConnectionException left
-    // unresolved by sending the same id again rather than placing a second order, the same guarantee
-    // getPartyPreferencesMessageId gives a cart.
-    // A delivery must name an address, either an id from this customer's own list or a full address
-    // sent directly - see requireDeliveryAddress.
+    // 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.
+    // 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 the
-        // server last confirmed it, not a value some observer may still hold
+        // Read from the store, not the published Business, so the order reflects the cart as stored,
+        // not a value an observer may still hold
         const partyPreferencesMessage = await Model.getCache().readPartyPreferences(target.containerName);
         const shoppingList = partyPreferencesMessage === null
             ? ShoppingList.EMPTY
@@ -205,21 +186,19 @@ 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 creation time for both, and it is what the order was placed at
+        // One time for both messages, which is when the order was placed
         const now = BigInt(Date.now());
-        // Order and emptied cart in one request: two calls could leave a customer with an order placed
-        // but a cart still full, if the second one failed
+        // 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
         await this.pushBusinessMessages(target, [
             ProtoMap.buildOrderMessage(orderId, target.senderId, shoppingList, fulfillmentMode, deliveryAddressId, deliveryAddress, note, now),
-            // fulfillmentMode is the order's, not left as whatever the cart held: placing an order is
-            // this customer's own choice of how it is fulfilled, freshly made, so it is what
-            // defaultFulfillmentMode should offer next time rather than a possibly stale earlier one.
+            // The customer's latest choice of fulfillmentMode, for defaultFulfillmentMode to offer next time
             ProtoMap.buildPartyPreferencesMessage(Ids.getPartyPreferencesMessageId(target.businessLink.id), partyPreferencesMessage, target.senderId, null, fulfillmentMode, now),
         ]);
     }
     // #endregion
-    // Throws if a profile is already held; otherwise stores the credentials every later call signs
-    // with. The one step signIn and createUser share before parting ways over how each gets a profile.
+    // Throws if a profile is already held, otherwise stores the credentials every later call signs
+    // with. The step signIn and createUser share.
     beginSignIn(authenticationMethod, subjectId, authenticationToken) {
         if (this._profile.value !== null)
             throw new IllegalOperationException("A user is already signed in");
@@ -228,39 +207,38 @@ class Model {
         this._authenticationToken = authenticationToken;
     }
     // #region Pushing
-    // One push, plus everything that follows a server accepting it. The messages go out in one
-    // request, with how far this business container's reads have got, and the server answers with
-    // these messages under their assigned update numbers, and no more: a push is not a read. They are
-    // stored, and move no cursor, so, the next read is sent them again, and anything somebody else
-    // changed in the meantime comes with them. A server that refuses the push fails the call
-    // itself, same as any other Service call on a bad status, so there is nothing left here to check:
-    // reaching the write below already means the server took it.
+    // 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.
     async pushBusinessMessages(target, messages) {
         const cache = Model.getCache();
         const messageUpdateNumber = await cache.readMessageUpdateNumber(target.containerName);
         const authTokens = await this.requireBusinessAuthTokens(target.containerName, target.businessLink);
         const response = await Model.getService().businessSyncIn(ProtoMap.buildBusinessSyncInRequest(messageUpdateNumber, messages), ProtoMap.buildAuthTokens(authTokens));
         await this.storeIssuedTokens(ProtoMap.getResponseAuthTokens(response), target.containerName);
-        // Stored exactly as the response carried it, entities and all - no stamping step, because the
-        // server already answered with the messages themselves rather than a bare number to reapply
+        // Stored as the response carried them: the server answers with the messages themselves, so
+        // nothing is stamped
         const changeCount = await cache.writeMessages(target.containerName, ProtoMap.getSyncInResponseMessages(response));
         // What the store took decides whether anything is published - see the Publishing region
         if (changeCount !== 0)
             this.publishBusiness(await cache.readBusiness(target.containerName));
     }
-    // Amends whatever cart containerName already holds and writes the result back to the cache -
-    // nothing is pushed to the server. updateCartLocalOnly's two callers differ only in which
-    // container, which id, and which 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.
+    // 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.
     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())));
-        // Published on what the store took, the same rule every read and push keeps
+        // Published on what the store took, as for every read and push
         if (changeCount !== 0)
             this.publishBusiness(await cache.readBusiness(containerName));
     }
-    // The business being browsed, refused by name when there is none or it has not been read yet.
-    // Shared by every write, because neither has anything to write to without it.
+    // The id of the business being browsed, for a write. Throws if there is none or it has not been
+    // read yet.
     requireBusinessBeingBrowsed() {
         const businessId = this._businessId;
         if (businessId === null)
@@ -269,10 +247,9 @@ class Model {
             throw new IllegalOperationException(`Business ${businessId} has not been read yet, so there is nothing to write to`);
         return businessId;
     }
-    // Everything a write needs, gathered before anything is built. Each precondition is refused by
-    // name rather than one unhelpful "not ready": no business browsed, one not yet loaded, no profile
-    // loaded, or a customer who isn't a member - the last being what the server would refuse anyway,
-    // for want of a link token to sign with.
+    // 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.
     requireCustomerOfBusiness() {
         const businessId = this.requireBusinessBeingBrowsed();
         const business = this._business.value;
@@ -291,15 +268,15 @@ class Model {
             countryCode: business.countryCode,
         };
     }
-    // Where an order is delivered: an id into this customer's own address list (the same list
-    // Order.deliveryAddressId resolves against) or a full address sent directly. An id not in that
-    // list would leave the business holding an order it can't read, so it's refused here rather than
-    // sent; a full address carries everything it needs and so isn't checked against the list.
+    // 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
+    // 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 is the case that names neither, which is normal - see Order.deliveryAddressId
+            // Pick-up names 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;
@@ -310,23 +287,18 @@ class Model {
     // #endregion
     // #region The four calls of Service, each as this model makes it
     //
-    // Each is complete in itself: it pages, caches every page as it arrives, files what the server
-    // issued, and publishes what the cache then holds.
-    // Reads in the business being browsed. An anonymous visitor reads it straight, under its own
-    // businessId. A signed-in customer reads it under their own container instead - see
-    // getBusinessContainerName - joining as a customer first if not already linked - see
-    // requireBusinessLink.
-    // Throws NotFoundException, from either, when the business is not one a storefront can open,
-    // whether or not this customer has joined it, and that is the answer to any read of it, the first
-    // or a later one: a business can stop being open after it was cached. The server says so when the
-    // business does not exist, has been deleted, or does not allow customers to join it. Whether it
-    // has turned online shopping on the server does not say: this decides, once everything the server
-    // sent has been read, from the settings that it then holds. What was cached is left as it is,
-    // except that a business that is no longer the one that the businessId names is given up for the
-    // one that is, if there is one: see syncBusinessContainer.
-    // isStartedOver is for the one time that this calls itself: the link that a customer's profile found by the businessId is of
-    // a business that no longer has it, which syncBusinessContainer finds out once it has read the business. The profile is read again,
-    // as it is what said so, and this starts again from what it now says - which may be a business that the customer has to join, or none.
+    // Each pages, caches every page as it arrives, files what the server issued, and publishes what
+    // the cache then holds.
+    // 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, or nothing to buy, is
+    // decided here (see syncBusinessContainer). 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.
     async businessSyncIn(isStartedOver = false) {
         const businessId = this._businessId;
         if (businessId === null || businessId.length === 0)
@@ -340,24 +312,20 @@ class Model {
         const cache = Model.getCache();
         const containerName = Model.getBusinessContainerName(link);
         const anonymousName = ContainerNames.forBusiness(businessId);
-        // What this device read while nobody was signed in, folded into the container it is read
-        // under now - the same rule the server's own pages take: the later of two copies per entity by
-        // update number is kept, so a tombstone wins over what it deleted. Unconditional, since a
-        // returning customer's own container can easily be the staler of the two. It moves no cursor:
-        // that container has not been read for any of this, and is read from where its own reads got to.
-        // Not the cart, which is settled below: the two containers hold it under different ids, so a
-        // merge keyed on entity id would file the visitor's as a second cart instead of replacing one.
-        // Nor one that holds another business than the link is of: what was read under the businessId while nobody was
-        // signed in is of the business that the businessId named then, which is not the one the link is of once the
-        // businessId has been given up and taken by another. Folded in, the one container would hold two businesses, and
-        // which of them it answers with would be decided by nothing - and a cart is the cart of the business it was built in.
-        // One that holds no business at all has nothing to contradict the link with, and is folded in: a cart can be all that a
-        // visit left of it.
+        // Folds what this device read while nobody was signed in into the customer's container. The
+        // later copy of an entity, by update number, wins, as for the server's own pages, so a tombstone
+        // beats what it deleted. No cursor moves.
+        // Left out:
+        // - The cart, settled below. The containers hold it under different ids, so a merge would file
+        //   the visitor's as a second cart.
+        // - A container holding a different business than the link's. Its businessId may since have
+        //   been given up and taken by another, and a cart belongs to the business it was built in.
+        // A container with no business is folded in, since a cart can be all a visit left.
         const anonymousContainer = await cache.readBusiness(anonymousName);
         const anonymousEntityId = ProtoMap.getBusinessResponseBusinessEntityId(anonymousContainer);
         const anonymous = anonymousEntityId !== null && anonymousEntityId !== link.businessId ? null : anonymousContainer;
-        // Out of the messages just read, rather than a second read of the same container -
-        // partyPreferencesMessageFromMessages picks the same one readPartyPreferences(anonymousName)
+        // Taken from the messages just read, not a second read of the container.
+        // partyPreferencesMessageFromMessages picks the same message readPartyPreferences(anonymousName)
         // would.
         const anonymousPartyPreferences = anonymous === null ? null : ProtoMap.partyPreferencesMessageFromMessages(anonymous.messages);
         if (anonymous !== null) {
@@ -365,12 +333,13 @@ class Model {
             await cache.storeBusiness(containerName, anonymous);
         }
         const authTokens = await this.requireBusinessAuthTokens(containerName, link);
-        // The link names the business by its entity id, which the link token that signs this call has to be of
+        // 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 business that the link is of has another businessId now, and the profile that found the link by this one did not know
-        // it. Its container has been given up, and what is asked next of the server is what the profile says: read again, so that
-        // the link is found by this businessId or not, and the businessId that names another business is joined. Once - a profile
-        // that is read again and still finds the same link for the same businessId is the server contradicting itself
+        // 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
         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`);
@@ -378,91 +347,72 @@ class Model {
             await this.businessSyncIn(true);
             return;
         }
-        // THE CART A VISITOR BUILT BEFORE SIGNING IN. Signing in changes which container is being
-        // browsed, so without this it is simply left behind - and a customer has to build it again
-        // having just proved who they are.
+        // THE CART A VISITOR BUILT BEFORE SIGNING IN. Signing in changes the container being browsed,
+        // so without this the cart is left behind and the customer has to build it again.
         if (anonymousPartyPreferences === null)
             return;
-        // The visitor's cart holds taxes as raw codes, which mean something only within the country of
-        // the business it was built in. The anonymous container is where that was read from, and a cart
-        // is only ever stored once its business has been (see updateCartLocalOnly); failing that, the
-        // business being browsed is the same one.
+        // 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.
         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");
-        // Read after the sync, so this is weighed against what the server just settled rather than a
-        // local copy about to be replaced. Last written wins, by updatedAt.
+        // Read after the sync, so the comparison is against what the server just settled, not a local
+        // copy about to be replaced. The later updatedAt wins.
         const userPartyPreferences = await cache.readPartyPreferences(containerName);
         if (userPartyPreferences === null ||
             ProtoMap.getMessageUpdatedAt(anonymousPartyPreferences) >
                 ProtoMap.getMessageUpdatedAt(userPartyPreferences))
             await this.updateCart(ProtoMap.buildShoppingList(anonymousPartyPreferences, anonymousCountryCode));
-        // Dropped either way, carried over or beaten by the customer's own: the anonymous container is
-        // what the next visitor on this device reads, and a settled cart has no business staying there.
+        // Dropped either way, carried over or beaten by the customer's own. The next visitor on this
+        // device reads the anonymous container, and a settled cart should not stay there.
         await cache.deletePartyPreferences(anonymousName);
     }
-    // The plain businessId-named container: an anonymous read, before signing in or joining, or to
-    // learn a business's entity id while joining - see readJoinBusinessId.
+    // Reads the container named by the plain businessId: an anonymous read before signing in or
+    // joining, or to learn a business's entity id while joining (see readJoinBusinessId).
     async syncAnonymousBusiness(businessId) {
         await this.syncBusinessContainer(ContainerNames.forBusiness(businessId), businessId, null, null);
     }
-    // One business, cache first: what's already held publishes before the network is touched, so a
-    // returning customer sees the shop at once instead of a loading state. Cursors start from
-    // how far the reads of containerName have got, which it keeps, and not from zero, so a repeat call
-    // asks only what changed - see SyncCache.readBusinessCursors. Each page moves them as it is written.
-    // The business is named to the server by its entity id where this knows it, and by its businessId
-    // only where it does not: a caller that has a BusinessLink has its businessEntityId, and one that
-    // has read the business before has it in the container, from that read. Which of the two is
-    // decided once, by the first request, and every page after it is about the same business named the
-    // same way. The first read of a business by an anonymous visitor names it by its businessId, and its
-    // answer is what makes every later one not have to - except the read that is made again, below,
-    // when the business that the container holds has turned out not to be the one that the businessId names.
+    // 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.
+    // 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.
     //
-    // What decides whether the business can be opened is what the container holds once every page has been
-    // read and written, and not what the pages carried, which is only what changed: a read that has nothing
-    // new to send says nothing of what has not changed. It is looked at after every read, whether the read
-    // brought anything or not, and in this order:
-    // 1. That the business the container holds is the one that businessId names. A business keeps its entity
-    //    id when its businessId changes, and another can take the businessId it gave up, so a container that is
-    //    read by the entity id it was left with may hold a business that is not the one that businessId names
-    //    now. The business arrives changed when its businessId does, which is how this is seen, and it is seen
-    //    after the next read however long that is, as it is the container that is looked at. If it is not that
-    //    business, the container is given up and the business is read from the beginning by its businessId,
-    //    once: that finds a business that has it, or none, which the server says with a NotFoundException.
-    //    A read that a link names cannot be read again by the businessId, as a link token is refused with
-    //    one, and the link names the one business that it is of. Its container is given up all the same, and
-    //    it answers false: the link was found from what the profile said of the businessId, which is out of
-    //    date, so the caller starts again from a profile that is read again - see businessSyncIn.
-    //    Answers true when the container holds the business that businessId names.
-    // 2. That the business has turned online shopping on, which is the general settings it holds saying so.
-    //    Settings it holds none of, because it has made none or has deleted them, do not. The server does not
-    //    refuse a business for this, so this is where a business that has not is a NotFoundException, the
-    //    same one as the server's for the businesses it does refuse, to every caller and every read.
-    // 3. That the business has something that a customer can buy: a product that is enabled, that it does not sell
-    //    only offline, and that has a package with a price. A business with none, because it has made none, has
-    //    turned them all off, or sells them all offline, is not a shop that there is anything to show or to order
-    //    from, and is a NotFoundException as well. That is decided from the whole of what the container holds, as
-    //    the first two are, and so it is decided when the last page has been written.
-    // firstAuthTokens are those of the link that businessEntityId is of, and none when that is none: they sign the reads that
-    // name the business by it, and a read by the businessId is signed with nothing, however it came to be made.
+    // 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,
+    //    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.
+    // 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.
+    // 3. The business has something to buy: an enabled product, not sold only offline, with a priced
+    //    package. Otherwise it throws NotFoundException too.
     async syncBusinessContainer(containerName, businessId, businessEntityId, firstAuthTokens) {
         const cache = Model.getCache();
         const cached = await cache.readBusiness(containerName);
         const cachedBusiness = Model.buildPublishable(cached);
-        this.publish(cachedBusiness); // Unless it is a business that is not open - see publishBusiness
-        this._isPublishedBusinessVetted = false; // Until this has read it to the end
-        // The entity id that an earlier read of this container left in it: what a business is named by when no link names
-        // it. It is how the business was found then, and it may not be what the businessId finds now: a business can have
-        // its businessId given up and taken by another, or changed.
+        this.publish(cachedBusiness); // Null if online shopping is off, see publishBusiness
+        this._isPublishedBusinessVetted = false; // Until the read ends
+        // The entity id an earlier read left in this container. It names the business when no link
+        // 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 - which decides the publish at the end
+        // What the store accepted (the blobs it stored). 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 that the business cannot be opened: what was published from the cache, before it was asked, 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 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
             if (error instanceof NotFoundException)
                 this.publishBusiness(null);
             throw error;
@@ -470,60 +420,61 @@ 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, and not by a link, which names the business that it is of and no other
+        // Named by the cached entity id, not by a link, which names only its own business
         if (businessEntityId === null && cachedEntityId !== null && !Model.isBusinessNamed(held, businessId)) {
-            // What has been read of one business is no guide to what has not been read of another, so, none of the container
-            // is kept, nor how far it was read, and the business that the businessId names is read from the beginning. That is with
-            // no attachment url held either, which is why the expiry is zero and not that of the container's: the url it held was the
-            // old business's, which has been given up with it, and a server sent its expiry would take the new business to have it and
-            // send none, leaving every photo of it without one. Signed with nothing, a link token being refused with a 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
             await cache.deleteBusiness(containerName);
             this.publishBusiness(null);
             await this.readBusinessPages(containerName, businessId, new SyncState(SyncKeys.BUSINESS_SYNC_IN), 0n, null);
             held = await cache.readBusiness(containerName);
             isPublishedStale = true;
         }
-        // What the businessId finds is the business that has it, so, one that does not is the server contradicting itself
+        // 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, which is of a business that no longer has the businessId. It cannot be read again by the businessId,
-        // as a link token is refused with one, so, the container is given up as above and it is the caller's to start again
+        // 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
         if (businessEntityId !== null && !Model.isBusinessNamed(held, businessId)) {
             await cache.deleteBusiness(containerName);
             this.publishBusiness(null);
             return false;
         }
-        // A container that holds no business is not one that this can say anything of: that is a failure of its own, and
-        // not a business that has not turned online shopping on - see readJoinBusinessId
+        // 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)
         if (ProtoMap.getBusinessResponseBusinessEntityId(held) !== null && !ProtoMap.isBusinessResponseOnlineShoppingOn(held)) {
-            // What was published from the cache, before the network was asked, is of the business as it was when it was open,
-            // which is not what it is now: nothing of a business that cannot be opened is 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, 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)
             this.publishBusiness(null);
             throw new NotFoundException("The business has not turned online shopping on");
         }
-        // What the container holds now, built once for this and for the publish below: the one that was built from the cache
-        // before the network was asked, when the read has changed nothing of it
+        // What the container holds now, built once for this check and the publish below. When the read
+        // changed nothing, it is the one built from the cache.
         const business = isPublishedStale ? Model.buildPublishable(held) : cachedBusiness;
         if (business !== null && business.catalog.productCount === 0) {
-            // Nothing that a customer can buy is a shop that is not found, and is not shown, whatever the cache published
+            // A shop with nothing to buy is not found and not shown, even if the cache published it
             this.publishBusiness(null);
             throw new NotFoundException("The business has nothing that a customer can buy");
         }
-        // A read the store took nothing from re-renders nobody - already published above from cache,
-        // and nothing here changes what a later read of this container answers
+        // A read the store took nothing from re-renders nobody: the cache was published above, and
+        // nothing here changes what a later read answers
         if (isPublishedStale)
             this.publish(business);
-        // What is published now is what was read to the end, and is the business that the businessId names, and is open
+        // What is published now was read to the end, is the business the businessId names, and is open
         this._isPublishedBusinessVetted = true;
         return true;
     }
-    // Reads every page of a business that the server has for the cursors it is given, and writes each into the
-    // container as it arrives. The business is named by its entity id or by its businessId, which is decided by
-    // the first request, and every page after it is about the same business named the same way. Answers what the
-    // store accepted - the blobs it stored.
-    // firstAuthTokens are those of a link, and a link token is refused with a businessId, so a read that names the business by
-    // it is sent none, whatever it is given: no request that names a businessId carries one, from any of the paths that make it.
+    // 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.
     async readBusinessPages(containerName, business, cursors, attachmentBaseUrlExpiry, firstAuthTokens) {
         const cache = Model.getCache();
         let request = ProtoMap.buildBusinessSyncOutRequest(business, cursors, attachmentBaseUrlExpiry);
@@ -532,12 +483,12 @@ class Model {
         for (;;) {
             const page = await Model.getService().businessSyncOut(request, authTokens);
             const issued = ProtoMap.getResponseAuthTokens(page);
-            // Written as it arrives, not at the end, so an interrupted read merely repeats itself instead
-            // of losing pages already received. Entities and tombstones go in together, one write per page.
+            // Written as each page arrives, so an interrupted read repeats work and loses no pages
+            // already received. Entities and tombstones go in together, one write per page.
             changeCount += await cache.writeBusiness(containerName, page);
             await this.storeIssuedTokens(issued, containerName);
-            // Null when this was the last page: fewer than a full page came back, or a full one advanced
-            // no cursor - which only a server breaking its own ordering can do
+            // Null on the last page: fewer than a full page came back, or a full one advanced no cursor
+            // (only a server breaking its own ordering does that)
             const next = ProtoMap.nextBusinessSyncOutRequest(request, page);
             if (next === null)
                 return changeCount;
@@ -546,17 +497,17 @@ class Model {
             authTokens = ProtoMap.refreshAuthTokens(authTokens, issued);
         }
     }
-    // Whether a response holds the business that businessId names, or holds none at all, which says nothing against it:
-    // only a business that has another businessId is another business. A business id is compared as the server finds
-    // one, in whatever case it is written and however it is padded
+    // 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)
     static isBusinessNamed(response, businessId) {
         const heldBusinessId = ProtoMap.getBusinessResponseBusinessId(response);
         return (heldBusinessId === null ||
             canonicalizeBusinessId(heldBusinessId) === canonicalizeBusinessId(businessId));
     }
-    // The BusinessLink of this profile for the named business, joining as a customer first (once) if
-    // not linked yet. A business in the profile with no matching link is a server inconsistency, not
-    // something a join would fix, so that case throws directly.
+    // 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.
     async requireBusinessLink(businessId, profile) {
         if (profile.user === null)
             throw new IllegalOperationException("No profile has been read, so who is browsing is not known");
@@ -567,25 +518,25 @@ class Model {
             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());
-        // Attempted once: a join that still leaves no link is the server contradicting itself, not
-        // something retrying would fix.
+        // Tried once: a join that leaves no link is the server contradicting itself, and retrying
+        // would not fix it.
         const joined = this._profile.value;
         const joinedLink = joined === null ? null : Model.findBusinessLink(joined, businessId);
         if (joinedLink === null)
             throw new InternalServerException(`Joining business ${businessId} did not leave this customer's profile naming it`);
         return joinedLink;
     }
-    // The entity id to join, for a business this profile doesn't list yet. Read off the Business
-    // already held, if an anonymous visit left one behind and read it to the end, or off a fresh anonymous read otherwise.
-    // A business that is only published from the cache, by a read that has not ended, is not one that has been found to
-    // be open and to be the one that the businessId names, and a customer is not joined to it on that account.
+    // The entity id to join, for a business this profile does not list yet. Taken from the Business
+    // already held, if an anonymous visit read it to the end, else from a fresh anonymous read.
+    // A business published from the cache by a read that has not ended is not known to be open or to
+    // be the one the businessId names, so a customer is not joined to it.
     async readJoinBusinessId(businessId) {
         const alreadyHeld = this._business.value;
         if (alreadyHeld !== null && this._isPublishedBusinessVetted)
             return alreadyHeld.id;
         await this.syncAnonymousBusiness(businessId);
-        // A business that is not there is a NotFoundException of the read above. Reaching here with none
-        // published is the server answering with no Business at all, which is its own failure
+        // 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
         const business = this._business.value;
         if (business === null)
             throw new InternalServerException(`The read of business ${businessId} answered with no Business`);
@@ -598,8 +549,8 @@ class Model {
                 return business;
         return null;
     }
-    // Null unless both the business and a link naming this profile's own user are present - a
-    // membership is both of those together, not either alone.
+    // Null unless both the business and a link naming this profile's user are present: a membership
+    // needs both.
     static findBusinessLink(profile, businessId) {
         const user = profile.user;
         const businessEntity = Model.findBusinessEntity(profile, businessId);
@@ -610,22 +561,20 @@ class Model {
                 return link;
         return null;
     }
-    // Where this customer's own copy of a business lives, named for the BusinessLink rather than
-    // Business.businessId so a signed-in customer's data never mixes with an anonymous visit to the
-    // same storefront. Hex for the same reason as Ids.toStorageHexString: a fixed-width,
+    // Where this customer's copy of a business lives. Named for the BusinessLink, not
+    // Business.businessId, so a signed-in customer's data does not mix with an anonymous visit to the
+    // same storefront. Hex for the reason given at Ids.toStorageHexString: a fixed-width,
     // case-sensitive name.
     static getBusinessContainerName(link) {
         return ContainerNames.forBusiness(Ids.toStorageHexString(link.id));
     }
-    // The credentials that sign a call about a customer's own business container. The authentication
-    // token always comes from memory, not a cache read - same as buildProfileAuthTokens, since a
-    // stored AuthTokens never persists it.
-    // The user token and link token are read independently, not as one object: storeIssuedTokens
-    // overwrites the whole blob per call, so trusting only that would lose whichever token the last
-    // call didn't reissue. Each falls back to its own source instead - the profile container's user
-    // token, this link's own linkToken - which is exactly what a fresh membership lacks and what the
-    // write below now gives this container to reissue over.
-    // A link with no linkToken at all is a server inconsistency: thrown rather than sent unsigned.
+    // 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.
+    // A link with no linkToken is a server inconsistency, and throws rather than sending unsigned.
     async requireBusinessAuthTokens(containerName, link) {
         const authenticationMethod = this._authenticationMethod;
         const authenticationToken = this._authenticationToken;
@@ -646,10 +595,9 @@ class Model {
             await cache.writeAuthTokens(containerName, authTokens);
         return authTokens;
     }
-    // The profile of whoever is signed in, paged the same way. Everything it earns files in the
-    // profile container - this call is entirely about the caller, so its AuthTokens never carries a
-    // link token; the only linkToken the protocol sends travels inside a BusinessLink, stored as part
-    // of the profile.
+    // 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.
     async profileSyncIn(firstRequest, firstAuthTokens) {
         const containerName = this.getProfileContainerName();
         if (containerName === null)
@@ -659,8 +607,8 @@ class Model {
         let request = firstRequest;
         let authTokens = firstAuthTokens;
         let changeCount = 0;
-        // Tracked across every page, not just the first: a profile long enough to page could put the
-        // joined link and business on different pages, and two flags cost nothing next to relying on that.
+        // Tracked across all pages: a profile long enough to page could put the joined link and
+        // business on different pages.
         const joinBusinessId = firstRequest.joinBusinessId;
         let hasJoinedLink = false;
         let hasJoinedBusiness = false;
@@ -675,8 +623,8 @@ class Model {
             if (next === null)
                 break;
             request = next;
-            // Each call after the first is signed with whatever the page before it reissued - a read of
-            // many pages is where a token can fall due part way through
+            // 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
             authTokens = ProtoMap.refreshAuthTokens(authTokens, ProtoMap.getResponseAuthTokens(page));
         }
         // As above: nothing the store took, nothing published
@@ -685,40 +633,35 @@ class Model {
             response = await Model.getCache().readProfile(containerName);
             this.publishProfile(response);
         }
-        // Last, so everything that arrived is cached and published first: those pages weren't at
-        // fault, the join was
+        // Last, so everything that arrived is cached and published first. The pages were not at fault,
+        // the join was
         Model.requireJoinedBusiness(joinBusinessId, hasJoinedLink, hasJoinedBusiness);
         return response;
     }
-    // The sign-up call. Never paged: resending it would create a second user, and a caller signing up
-    // has at most their new User, one BusinessLink and the Business it names. It can join a business
-    // in the same call, and a join's requirements are the same as on a profile read - one response
-    // instead of several is the only difference.
+    // The sign-up call. Not paged: resending it would create a second user, and a new caller has at
+    // most their User, one BusinessLink and the Business it names. It can join a business in the same
+    // call, with the same join requirements as a profile read, in one response.
     async createProfileOnServer(request, authTokens) {
         const response = await this.writeProfileResponse(await Model.getService().createUser(request, authTokens));
         const joinBusinessId = request.joinBusinessId;
-        // Raised after the response is cached and published, as on a profile read - sharper here since
-        // the User exists regardless of the join, so discarding this response and signing up again
-        // would create a second one
+        // Raised after the response is cached and published, as on a profile read. It matters more
+        // here: the User exists regardless of the join, so discarding the response and signing up
+        // again would create a second one
         Model.requireJoinedBusiness(joinBusinessId, ProtoMap.hasJoinedBusinessLink(joinBusinessId, response), ProtoMap.hasJoinedBusiness(joinBusinessId, response));
         return response;
     }
     // #endregion
     // #region Driving one call
-    // A join that was asked for but not answered. Shared by both calls that can carry a
-    // joinBusinessId, since a join answers the same two things regardless of which one asked: the
-    // BusinessLink (the membership) and the Business it names. Both are needed to reach a business -
-    // the link for its token, the Business for the url-friendly id everything else is built from -
-    // so either one missing leaves the caller told it is a customer of something it cannot reach.
+    // Throws when a requested join is not answered with both the BusinessLink (the membership, whose
+    // token signs calls) and the Business it names (whose businessId everything else is built from).
+    // 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 one of Exceptions.ts: nothing the caller passed was wrong - the server
-    // answered 200 and left out what was asked for - so a caller can retry or carry on with what is
-    // cached. 500 is the closest code, and the one that says retrying is worth it.
-    //
-    // Only a joinBusinessId a server could act on is checked (Java Business.isValidBusinessId's
-    // test, which Constants.ENTITY_ID_NULL also fails, so "no join asked" needs no case of its own).
-    // An id that is not a business entity id never gets as far as here: a server refuses it (400),
-    // which fails the call itself, and sending one is the caller's bug, not the server's.
+    // A ServiceException, not a caller error: the server answered 200 and left out what was asked
+    // for. 500 says retrying is worth it.
+    // 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.
     static requireJoinedBusiness(joinBusinessId, hasBusinessLink, hasBusiness) {
         if (Ids.getEntityTypeId(joinBusinessId) !== proto_Constants.BUSINESS_ENTITY_TYPE_ID)
             return;
@@ -731,14 +674,13 @@ 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 whatever it reissued
-    // filed against the same container. Answers how much of it the store took, which is what decides
-    // whether anything is published. Shared by all three calls that receive one - each page of a read,
-    // a sign up and an update - so none of them can come to cache a response differently from the
-    // others, or file a token in a different place. Publishing is not in here: a read publishes once
-    // for a whole loop of these, and the other two once each.
-    // Only a page of a read moves the cursors of the container. 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.
+    // 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.
+    // 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) {
         const cache = Model.getCache();
         const changeCount = isPageOfRead
@@ -747,13 +689,11 @@ class Model {
         await this.storeIssuedTokens(ProtoMap.getResponseAuthTokens(response), containerName);
         return changeCount;
     }
-    // What a non-sync-out profile call leaves behind: the response cached and published, same as a
-    // paged read, minus paging neither needs. Both calls that come through here - a sign up and an
-    // update - publish on exactly the rule a read keeps, which is what the store took. An update
-    // publishes nothing today only because the server puts no entities in that response: it answers
-    // with whatever it reissued and nothing else, the caller already knowing what it sent. The day it
-    // answers with the stored User - whose update number and updated time a caller cannot know - this
-    // publishes it with no change here.
+    // 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.
     async writeProfileResponse(response) {
         const containerName = this.getProfileContainerName();
         if (containerName === null)
@@ -762,15 +702,14 @@ class Model {
             this.publishProfile(await Model.getCache().readProfile(containerName));
         return response;
     }
-    // Files what a call earned against the container that call was about: a profile call's tokens in
-    // the subject's profile container, a business call's in that business's container. Which call it
-    // was decides this, not which token arrived - a token carries nothing saying what it's about, so
-    // only the caller, which knows what it asked, can attribute one. A business sync out that reissues
-    // a user token still files that copy with the business it came back from.
-    // A profile call never carries a link token here - a membership's link token travels inside its
-    // BusinessLink entity instead, stored with the rest of the profile.
+    // 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.
+    // 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, where surfacing it would turn a working read into a thrown one.
+    // trip, and surfacing it would turn a working read into a thrown one.
     async storeIssuedTokens(issued, containerName) {
         if (issued === undefined)
             return;
@@ -783,16 +722,15 @@ class Model {
     }
     // #endregion
     // #region Containers and credentials
-    // Where this subject's profile and tokens are cached, keyed by authentication method plus
-    // subject id since two identity providers could otherwise issue the same subject id. Null when
-    // signed out; several can coexist, so signing back in finds this subject's own profile.
+    // 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.
     getProfileContainerName() {
         return this._authenticationMethod === null || this._subjectId === null
             ? null
             : ContainerNames.forProfile(`${this._authenticationMethod}.${this._subjectId}`);
     }
-    // The profile container name, when a profile is already known to exist - throws rather than
-    // silently building on a signed-out state the caller has already ruled out.
+    // The profile container name, for when a profile is known to exist. Throws if signed out.
     requireProfileContainerName() {
         const containerName = this.getProfileContainerName();
         if (containerName === null)
@@ -800,7 +738,7 @@ class Model {
         return containerName;
     }
     // Signs a call about the caller alone, or null if signed out. Rereads the user token from the
-    // profile container each time, since a call can reissue it. Carries no linkToken - see
+    // profile container each time, since a call can reissue it. Carries no linkToken. See
     // requireBusinessAuthTokens for a business call.
     async buildProfileAuthTokens() {
         const authenticationMethod = this._authenticationMethod;
@@ -823,28 +761,23 @@ class Model {
     // #endregion
     // #region Publishing
     //
-    // What a read publishes turns on how much the store accepted - blobs stored plus ids deleted,
-    // summed across every page - not on what the response carried. They differ because the store
-    // keeps a blob only when its eTag is later, so a response the server sent can still be rejected
-    // in full - a cursor that moved without its eTag moving is resent an entity already cached.
-    // Publishing that would re-render every observer over an identical value, which the count avoids,
-    // and nothing is lost: a response the store took nothing from can't change what a later read
-    // answers.
-    // All four calls use this, which is why an update publishes nothing - see writeProfileResponse.
-    // A business that has not turned online shopping on is not published, whatever the container holds of it: what is
-    // published is then no business, as it is a business that cannot be opened, which a read throws for. Without this,
-    // the cache-first publish of a container that a read of such a business left behind would show it again before the
-    // next read is refused, and a customer could be joined to it. A read that finds that a business that it published from
-    // the cache has stopped being open, or that the server says cannot be opened, takes it back: it publishes none.
-    // What is published from the cache is not taken to be open all the same until the read has ended (see
-    // _isPublishedBusinessVetted), which is what readJoinBusinessId goes by.
+    // 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.
+    // 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).
     publishBusiness(response) {
         this.publish(Model.buildPublishable(response));
     }
     publish(business) {
         this._business.value = business;
     }
-    // The business that a response holds, or none when there is no response or the business has not turned online shopping on
+    // The business a response holds, or null when there is no response or online shopping is off
     static buildPublishable(response) {
         return response === null || !ProtoMap.isBusinessResponseOnlineShoppingOn(response)
             ? null