toga-ai 1.0.553 → 1.0.554

package/knowledge/2.0/apps/api2/features/v2-rest-query-contract.md

@@ -47,7 +47,18 @@ controller.
 - **Pagination is `page` + `recordsPerPage`. There is no `limit`/`offset`.** Defaults:
   `recordsPerPage` **25**, `depth` **3**. Max `recordsPerPage` **10000** — exceeding it returns
   **`EV-13`** (HTTP 400).
-- **Sort:** `-field` = DESC, bare `field` = ASC. **Do not send `+`** for ascending.
+- **Sort:** `-field` = DESC, `+field` = ASC, bare `field` = ASC. All three are handled
+  (`V2.php` ~L3673–3682). **Prefer bare for ascending:** the query string is parsed *without*
+  urldecoding (see Encoding rules), so a client that percent-encodes the `+` as `%2B` sends a
+  field literally named `%2Bfield` and the sort is silently dropped. Bare has no such failure mode.
+- **A LIST select is `SELECT SQL_CALC_FOUND_ROWS DISTINCT <table>.<primaryKey>`** (`V2.php:3884`;
+  the aggregate-fields path is the one exception). Two consequences: (a) join fan-out collapses to
+  one row per record, so **duplicate child rows are invisible in the response** — a duplicate join
+  row is not a rendering bug you can see; (b) when the collapsed duplicates carry **different**
+  values in the sorted column, `ORDER BY` has more than one candidate value for a single output row
+  and that record's **position is non-deterministic**. Sorting on a joined column is only stable if
+  the join is genuinely 1:1, or the duplicates agree. Worked example:
+  [category tile sort order](../../toga2-commerce/features/category-tile-sort-order.md).
 
 ### ⚠ `depth` is not free — the default 3 re-reads child rows and races concurrent deletes
 
@@ -158,6 +169,15 @@ where=(field:op:value,LOGIC,field:op:value,(nested,OR,nested))
   invisible; re-request with `fields=` to force `EZ-2` and see the denied list.
 
 ## Change history
+- 2026-08-11 — **Corrected the sort contract and documented the `DISTINCT` LIST select.** The old
+  "do not send `+`" was wrong as an absolute: `V2.php` ~L3673–3682 explicitly handles `+` as ASC.
+  The real caveat is encoding — the query string is parsed without urldecoding, so a
+  percent-encoded `+` (`%2B`) becomes part of the field name and the sort is silently dropped;
+  bare remains the recommended ascending form. Also recorded that a LIST select is
+  `SELECT SQL_CALC_FOUND_ROWS DISTINCT <table>.<primaryKey>` (`V2.php:3884`), which hides duplicate
+  join rows entirely **and** makes `ORDER BY` non-deterministic for a record whose collapsed
+  duplicates disagree on the sorted column. Found while diagnosing storefront category tile
+  ordering (duplicate `AssortmentItems` rows for one item). (bala)
 - 2026-08-11 — Recorded that **`depth` (default 3) makes a response race concurrent deletes**:
   `getFullModelData()` re-loads each child by primary key via `_Model::initialize()`, whose build
   **throws** when the row is gone (*"Exactly 1 row was expected to be returned but 0 were"*),

package/knowledge/2.0/apps/toga2-commerce/INDEX.md

@@ -6,6 +6,7 @@
 | [Cart Bundle Submission & the bundleUuid Identity Contract](features/cart-bundle-submission-and-identity.md) | How cart **bundles** (kits) are turned into `SalesOrderItems` when a cart is submitted or an existing order is edited, and the **identity-field contract** every | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts, src/utils/formatSalesOrderBundlesFromApi.ts, src/stores/useCartStoreZu.ts, src/pages/OrderDetails/helpers/formatSalesOrderDataFromLocalStorage.ts, src/pages/OrderDetails/view/components/OrderItems.tsx |
 | [Cart Notification Emails — duplicate prevention](features/cart-notification-emails.md) | On the cart "Notifications" section a user can add CC email addresses to an order. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/stores/useEmailOptionsStore.ts, src/stores/useCartSalesQuoteZu.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts |
 | [Cart Page — config-driven form architecture (current state + planned refactor)](features/cart-page-config-architecture.md) | The Cart page (`src/pages/Cart/`) is the most config-heavy page in `toga2-commerce`. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/pages/Cart/view/cartForm/CartFormSection.tsx, src/pages/Cart/view/cartForm/CartFormRenderer.tsx, src/pages/Cart/view/EditCart.tsx, src/pages/Cart/view/EditOrder.tsx, src/pages/Cart/viewModel/useEditOrderOrEditCartViewModel.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts, src/hooks/useAssignClientFields.ts |
+| [Category Tile Order (AssortmentItems.sortOrder) — merchandising a storefront category](features/category-tile-sort-order.md) | **"Move item X to the front of category Y" is a DATA change, not a code change.** The order of item tiles on a storefront category page is driven by exactly one | src/pages/Filter/api/FilterApi.ts, src/pages/Filter/viewModel/useFilterViewModel.ts, api2/Component/Api/V2/V2.php, toga2-supply/src/pages/Items/api/itemsApi.ts |
 | [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Almost no user-facing text, field layout, or page config is hard-coded in `toga2-commerce`. | src/pages/Account/view/MySettingsView.tsx, src/contexts/helpers/getLoginSettings.ts, src/pages/Account/viewModel/useAccountViewModel.ts, src/fieldsConfig/index.ts, src/fieldsConfig/getClientLoginFields.ts, src/fieldsConfig/clientFields/COMPASS.json, src/fieldsConfig/clientFields/COMPASSCANADA.json, src/fieldsConfig/clientFields/QUAD.json, src/pages/Cart/api/CartApi.ts, src/hooks/useAuthenticationFlow.ts, src/contexts/AuthContext.tsx, src/pages/Login/viewModel/useLoginPageViewModel.ts, src/hooks/useAssignClientFields.ts, src/hooks/useDynamicConditionalFieldOptions.ts, src/stores/useFieldsStore.ts, src/components/BaseDetailField/BaseDetailField.tsx, src/components/NavIcons/NavIconItem.tsx, src/components/Submenus/AlertSubmenu.tsx, src/components/Submenus/types.ts, src/pages/Account/AccountPage.tsx, src/pages/Account/view/MyOrdersView.tsx, src/pages/GetSupport/GetSupportPage.tsx, src/pages/GetSupport/viewModel/useGetSupportViewModel.ts, src/queries/queries.ts, src/App.tsx, src/pages/Filter/FilterPage.tsx, src/pages/Filter/viewModel/FIELDS/COMPASS/ENGLISH/USER/FILTERPAGEFIELDS.json |
 | [Config-Driven Expedited Shipping Gating (Cart)](features/expedited-shipping-gating.md) | On the toga2-commerce **Cart** page, expedited shipping options (**"2nd Day EOB"** and **"Next Day Air"**) are only offered in the *Shipping Method* dropdown wh | toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/CartPage.tsx |
 | [Filter / Search-Results Page & the Two Search Entry Points](features/filter-search-results-page.md) | The storefront has **two distinct search entry points that render the same card component through completely different code paths and different FIELDS files**. | src/pages/Filter/FilterPage.tsx, src/pages/Filter/viewModel/useFilterViewModel.ts, src/pages/Filter/viewModel/FIELDS/COMPASS/ENGLISH/USER/FILTERPAGEFIELDS.json, src/pages/Filter/viewModel/FIELDS/COMPASSCANADA/FRENCH/USER/FILTERPAGEFIELDS.json, src/pages/Filter/viewModel/FIELDS/QUAD/ENGLISH/BUYER/FILTERPAGEFIELDS.json, src/components/Header/Header.tsx, src/pages/Home/view/components/BundlesSection.tsx, src/pages/Home/viewModel/FIELDS/COMPASS/ENGLISH/USER/HOMEPAGEFIELDS.json, src/components/Cards/BundleViewCard.tsx, src/utils/renderBadge.tsx, src/hooks/useAssignClientFields.ts |

package/knowledge/2.0/apps/toga2-commerce/features/category-tile-sort-order.md

@@ -0,0 +1,164 @@
+---
+title: Category Tile Order (AssortmentItems.sortOrder) — merchandising a storefront category
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-08-11
+owners: [bala]
+files:
+  - src/pages/Filter/api/FilterApi.ts
+  - src/pages/Filter/viewModel/useFilterViewModel.ts
+  - api2/Component/Api/V2/V2.php
+  - toga2-supply/src/pages/Items/api/itemsApi.ts
+related:
+  - filter-search-results-page.md
+  - ../architecture.md
+  - ../../api2/features/v2-rest-query-contract.md
+---
+
+## Summary
+
+**"Move item X to the front of category Y" is a DATA change, not a code change.** The order of
+item tiles on a storefront category page is driven by exactly one column —
+**`Client_<Client>.AssortmentItems.sortOrder`, ascending** — and nothing else. There is no
+merchandising UI, no per-tenant config key, and no client-side re-sort to override.
+
+The trap is that the obvious one-row `UPDATE` **does not work**: in MySQL `ORDER BY … ASC`,
+`NULL` sorts **before** every number, and these columns are normally all `NULL`. Setting only the
+target item to `1` leaves the still-`NULL` siblings ahead of it — the opposite of the request. You
+must give **every active item in that assortment** an explicit `sortOrder`.
+
+## How it works
+
+1. **Category browse** is the `/filter` page with a `category` query param and no `search` text.
+   `useFilterViewModel.ts` runs the `["assortmentItems", categoryUuid, currentPage]` query, which
+   calls `fetchAssortmentItems()` in `src/pages/Filter/api/FilterApi.ts`.
+2. That request joins `Items → AssortmentItems → Assortments` (plus `Personas_Items → Personas`
+   for non-admins), filters to the requested assortment uuid with `Items.isActive = 1` and
+   `Items.catalogId = 1`, pages at `recordsPerPage: 12`, and sorts with exactly:
+
+   ```ts
+   sort: ["AssortmentItems.sortOrder"]
+   ```
+
+3. **api2 treats a bare (unprefixed) sort field as ASC.** (`-` = DESC, `+` = ASC — see
+   [v2-rest-query-contract](../../api2/features/v2-rest-query-contract.md).)
+4. **The frontend never re-sorts.** The view model does a straight
+   `setSortedItems(assortmentItems.data.items)` — despite the `sortedItems` name, no sorting
+   happens there. **The API's row order is the final on-screen order.**
+
+So the only lever is the column. Ties (equal or all-`NULL` values) fall back to whatever MySQL
+returns, which is not a documented or stable order.
+
+## Making the change (the procedure)
+
+Assign an explicit `sortOrder` to **every active item** in the assortment — the two pinned ones,
+then the rest. Pattern (`<assortmentId>` from `Assortments`, item ids from `Items`):
+
+```sql
+# 1. pin the intended leaders
+UPDATE AssortmentItems
+SET sortOrder = 1
+WHERE
+	assortmentId = <assortmentId> AND
+	itemId = <firstItemId>;
+
+UPDATE AssortmentItems
+SET sortOrder = 2
+WHERE
+	assortmentId = <assortmentId> AND
+	itemId = <secondItemId>;
+
+# 2. every remaining ACTIVE item must get a value, or a NULL row jumps to the front
+UPDATE AssortmentItems ai
+	INNER JOIN Items i ON i.id = ai.itemId
+SET ai.sortOrder = 10
+WHERE
+	ai.assortmentId = <assortmentId> AND
+	ai.sortOrder IS NULL AND
+	i.isActive = 1;
+```
+
+Verify with the read the storefront actually performs — ordered, not just spot-checked:
+
+```sql
+SELECT
+	ai.id,
+	ai.itemId,
+	ai.sortOrder,
+	i.itemNumber,
+	i.isActive
+FROM AssortmentItems ai
+	INNER JOIN Items i ON i.id = ai.itemId
+WHERE ai.assortmentId = <assortmentId>
+ORDER BY ai.sortOrder ASC;
+```
+
+**Recommended, not required:** park **inactive** rows at a high value (e.g. `100`) as well. They
+are filtered out today by `Items.isActive = 1`, so they cost nothing now — but if someone
+reactivates one later it comes back with `sortOrder = NULL` and silently takes first position.
+
+## Gotchas
+
+- **`NULL` sorts FIRST in ASC.** The single-row `UPDATE` that "obviously" pins an item produces the
+  opposite result while looking correct in isolation. Always set the whole active set.
+- **Duplicate `AssortmentItems` rows exist and make order non-deterministic.** api2's LIST query
+  selects `SELECT SQL_CALC_FOUND_ROWS DISTINCT <table>.<primaryKey>` (`V2.php:3884`), so two
+  `AssortmentItems` rows for the same `itemId` collapse to **one visible tile** — which is why
+  nobody notices the duplicate. But if the duplicates carry **different** `sortOrder` values, the
+  `ORDER BY` has two candidate values for one output row and the position is unpredictable. When
+  duplicates exist, give them the **same** value or delete the extras. Check first:
+
+  ```sql
+  SELECT itemId, COUNT(*) AS rowCount
+  FROM AssortmentItems
+  WHERE assortmentId = <assortmentId>
+  GROUP BY itemId
+  HAVING rowCount > 1;
+  ```
+
+- **⚠ Editing an item's assortments in TOGa Supply WIPES `sortOrder`.** See Known open items —
+  any ordering you set is one supply edit away from being erased. Re-verify order after anyone
+  edits that item in supply.
+- **A refresh will NOT show the change.** The storefront persists its whole React Query cache to
+  `localStorage["commerce"]` with a 24h `staleTime`, so a warm browser replays the cached
+  response and the (correct) data fix looks like it failed — then gets "re-fixed". The reliable
+  check is **log out and back in** (logout removes the `commerce` key), or
+  `localStorage.removeItem('commerce')`; otherwise it appears within 24h. See
+  [architecture](../architecture.md) gotchas.
+- **This is data, so it does not ride a deploy.** No build, no release notes — which also means no
+  audit trail. Record the assortment id and the values you set in the ticket.
+
+## Known open items
+
+- **⚠ TOGa Supply resets `sortOrder` to `NULL` on any item-assortment edit — unfixed, no ticket
+  filed yet.** In `toga2-supply/src/pages/Items/api/itemsApi.ts`, `updateItemAssortments()`
+  (L645) reads the item's existing rows via `getAssortmentItems()` (L434), which requests only
+  `["assortment.name", "assortment.uuid", "uuid"]` — **never `sortOrder`** — then `DELETE`s every
+  row and `POST`s new ones whose payload carries only `item.uuid` + `assortment.uuid`. The
+  merchandising order is therefore silently destroyed and cannot be restored, because the old
+  values were never read. A fix must select `sortOrder`, and either preserve it on the re-POST or
+  stop the delete-then-recreate in favor of diffing.
+- **Same function: the re-POSTs are never awaited.** `updateItemAssortments()` builds
+  `addPromises` and returns without `await Promise.all(addPromises)` (the `DELETE`s above it *are*
+  awaited). Failures surface as unhandled rejections and the caller cannot know the writes landed.
+  Fire-and-forget `POST`s racing an awaited `DELETE` burst is also the most likely origin of the
+  duplicate rows described in Gotchas. (Related: parallel deletes on a collection can 500 the
+  response of a concurrent read — see
+  [v2-rest-query-contract](../../api2/features/v2-rest-query-contract.md).)
+- **Compass USA "Docking Station" reorder — SQL delivered, NOT executed.** See
+  [Compass USA profile](../../../clients/compass-usa/profile.md).
+
+## Change history
+- 2026-08-11 — Initial doc, from a read-only prod investigation of a Compass USA request to move
+  one item to the front of a category. Recorded that tile order comes solely from
+  `AssortmentItems.sortOrder ASC` (`FilterApi.ts:56`) with no client-side re-sort in
+  `useFilterViewModel.ts`; the **`NULL`-sorts-first** trap that makes a single-row `UPDATE`
+  backfire (the real assortment had `sortOrder = NULL` on all 16 rows); api2's
+  `DISTINCT <primaryKey>` LIST select (`V2.php:3884`) hiding duplicate join rows while making
+  `ORDER BY` non-deterministic when duplicates disagree; and that toga2-supply's
+  `updateItemAssortments()` wipes `sortOrder` (and never awaits its re-POSTs), making any fix
+  non-durable. (bala)

package/knowledge/2.0/apps/toga2-commerce/features/filter-search-results-page.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-07-28
-owners: ["tcox"]
+owners: ["tcox", "bala"]
 files:
   - src/pages/Filter/FilterPage.tsx
   - src/pages/Filter/viewModel/useFilterViewModel.ts
@@ -24,6 +24,7 @@ related:
   - 2.0/apps/toga2-commerce/architecture.md
   - 2.0/apps/toga2-commerce/features/client-fields.md
   - 2.0/apps/toga2-commerce/features/multi-tenant-theming.md
+  - 2.0/apps/toga2-commerce/features/category-tile-sort-order.md
 ---
 
 ## Summary
@@ -53,6 +54,10 @@ bug (see Change history).
 tenant × language × role (see [client-fields](client-fields.md) for the resolver). `FilterPage`
 `renderBundles` maps each result to a `BundleViewCard`.
 
+> **Third mode, same page:** with a `category` param and **no** `search` text, `/filter` is the
+> category *browse* page and runs a different query (`fetchAssortmentItems`) whose row order is
+> data-driven — see [category tile sort order](category-tile-sort-order.md).
+
 ### Home search → in-place filter
 
 The Home page's own lower search bar never leaves `/home`. `BundlesSection.tsx` reads

package/knowledge/INDEX.md

@@ -29,7 +29,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **talos** (TOGa IQ) — 7 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 9 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
-- **toga2-commerce** (TOGa Commerce) — 12 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga2-commerce** (TOGa Commerce) — 13 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 11 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 8 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 - **bdr** (BDR) — 0 doc(s) → [2.0/apps/bdr/INDEX.md](2.0/apps/bdr/INDEX.md)

package/knowledge/clients/compass-usa/profile.md

@@ -17,7 +17,7 @@ project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-08-06
+updated: 2026-08-11
 owners: [jcardinal, bala, tcox, apeterson, dfranks]
 files: []
 related:
@@ -32,6 +32,7 @@ related:
   - workflows/odp-duplicate-po-line-cleanup.md
   - ../../2.0/apps/worker2/features/compass-vip-support-importer.md
   - ../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
+  - ../../2.0/apps/toga2-commerce/features/category-tile-sort-order.md
   - ../../2.0/apps/toga2-commerce/features/cart-bundle-submission-and-identity.md
   - ../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
 ---
@@ -61,6 +62,17 @@ separate, related client (see its own profile).
   **Known data issue:** many Compass MacBooks are categorized `APPLE LAPTOP` /
   `MAC & ACCESSORIES`, not `COMPUTERS`, so those kits do **not** qualify for expedited — a
   catalog-data normalization matter, not a code gap.
+- **Category tile order is data, not code** — `Client_Compass.AssortmentItems.sortOrder ASC` is the
+  only lever; see
+  [Category Tile Order](../../2.0/apps/toga2-commerce/features/category-tile-sort-order.md) for the
+  `NULL`-sorts-first trap and the procedure.
+  **⚠ Pending prod data change (2026-08-11, delivered but NOT executed):** for
+  `Assortments.id = 9` ("Docking Station", all 16 rows had `sortOrder = NULL`), pin
+  `itemId 2712` / `9X3V1UT` → `1` and `itemId 2812` / `AW5M5UT-1` → `2`, and give the remaining
+  active rows an explicit value. Handed off for a DBA / the TOGa UI to run because session DB
+  access was read-only. Also outstanding for that assortment: park the 13 inactive rows at a high
+  `sortOrder`, and remove the duplicate `AssortmentItems` row `id 2982` (duplicate of `2981`, same
+  `itemId 2712`). Confirm whether this was applied before re-diagnosing tile order for Compass.
 - **Cross-kit bundle corruption (edit-order):** a `toga2-commerce` submit bug attributed kit
   line items and shared fees/warranties to the wrong kit; 55 Compass orders / 298 line items are
   corrupted in `Client_Compass.SalesOrderItems` (Canada and Quad: zero). The code fix is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.553",
+  "version": "1.0.554",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",