toga-ai 1.0.741 → 1.0.742

package/knowledge/clients/compass-usa/features/item-catalogs-and-duplicate-items.md

@@ -204,7 +204,11 @@ children" rule:
   re-catalogs it.** The `toga2-commerce` storefront relays whatever item `GET /v2/bundles/{uuid}`
   returns; its `catalogId = 1` filter guards standalone item search only, never bundles. So a kit
   whose `BundleItems.itemId` points at the wrong-catalog twin makes **every checkout POST the wrong
-  item** (434 rows / 110 bundles after the 2026-08-31 fold). Fix in data, not the frontend. See
+  item** (434 rows / 110 bundles after the 2026-08-31 fold). **The fix surface is the DB bundle rows
+  PLUS the serving cache, never the frontend code** — after the DB rows were restored, a **shared**
+  bundle cache (api2/`_underscore` response cache and/or a CDN in front of `/v2/bundles`) kept
+  serving the stale Agilant uuid to new checkouts (two different users still POSTed the Agilant 2427
+  uuid) until it was invalidated. See
   [catalog-fold reversal](../workflows/catalog-fold-reversal.md) and
   [bundle item visibility & selectability](../../../2.0/apps/toga2-commerce/features/bundle-item-visibility-and-selectability.md).
 - **⚠ `isFulfillable` is born on the catalog-2 (Agilant) item** and propagates to the client-facing
@@ -223,6 +227,11 @@ children" rule:
   [catalog-fold reversal](../workflows/catalog-fold-reversal.md).
 
 ## Change history
+- 2026-09-02 — Corrected the `BundleItems` fix surface: restoring the DB bundle rows is **not**
+  sufficient — a **shared** server-side bundle cache (api2/`_underscore` response cache and/or a CDN
+  in front of `/v2/bundles`) kept serving the stale Agilant uuid to new checkouts until it was
+  invalidated (proven by two different users still POSTing the Agilant 2427 uuid after the DB fix).
+  Fix surface = DB bundle rows **plus** the serving cache, never the frontend code. (jcardinal)
 - 2026-09-02 — **Resolved the flagged "distinct vs shared partNumber" tension**: the Agilant twins
   carry **distinct** part-number variants (the `#ABA` form ≠ the plain part number, e.g.
   `C40QYUC#ABA` vs `C40QYUC`), so table-wide `partNumber` uniqueness holds and the catalog-fold

package/knowledge/clients/compass-usa/workflows/catalog-fold-reversal.md

@@ -120,13 +120,28 @@ qualifiers):
 **Rehearse on a same-day full prod clone, then apply with a pre-run backup. CTO review gated the
 approach** (rehearse-on-clone, fail-loud, customer-scoped, tenant-locked).
 
-### Stragglers: `#ABA`-variant PO lines need a manual VendorItem re-map
-Because the `#ABA` twins share no part number, neither the merge's part-number map nor a
-partNumber-twin re-point catches PurchaseOrder lines sitting on them. These were fixed by an
-**explicit VendorItem mapping**, scoped to **pending `customerId = 2` PO lines**, then clearing
-`PurchaseOrders.dtSubmitted` so the PO re-transmits: VendorItem **3845 → 3597** @ `945.17`,
-VendorItem **3884 → 3600** @ `1627.38`. Why a mis-mapped PO line transmits the wrong SKU + cost
-and drops to EMAIL rather than cXML:
+### Stragglers: broken-window orders need a manual, by-id re-map (SO item + PO VendorItem)
+Orders created **before** the data fix + cache flush stay on the Agilant twin and must be
+re-pointed by hand — the `#ABA` twins share no part number, so neither the merge's part-number map
+nor a partNumber-twin re-point catches them. The pattern per straggler, scoped to **pending
+`customerId = 2` lines**:
+1. **`SalesOrderItems.itemId`** — re-point the Agilant twin → the Compass twin.
+2. **`PurchaseOrderItems.vendorItemId` + `cost`** (if a PO was already built) — re-point to the
+   Compass `VendorItem` (correct SKU + cost).
+3. **`PurchaseOrders.dtSubmitted = NULL`** — so cron 2 re-transmits the PO correctly (cXML, right
+   SKU/cost).
+
+Verified twin / VendorItem mappings this session:
+
+| Agilant item | Compass item | Compass VendorItem | Vendor SKU | Cost |
+|---|---|---|---|---|
+| 2427 (`C40QYUC`)   | 2157 | 3597 | 5775600 | 945.17 |
+| 2431 (`C40QYUC-1`) | 2158 | 3598 | 7761063 | 945.17 |
+
+PO `VendorItem` re-maps: **3845 → 3597** @ `945.17`, **3884 → 3600** @ `1627.38` (`B7HJ2UC#ABA`).
+Orders fixed: `50312344-1`, `50312409-1`, `SA136868`, `SA136874`, plus the earlier 5 pending
+(`SA136819`, `SA136820`, `SA136845`, `SA136852`, `SA136862`). Why a mis-mapped PO line transmits the
+wrong SKU + cost and drops to EMAIL rather than cXML:
 [MITS PO transmission to vendors](../features/mits-po-transmission-to-vendors.md).
 
 ## The folded `BundleItems` was the storefront's ongoing bad-order source
@@ -135,10 +150,32 @@ rows across 110 bundles**. The `toga2-commerce` storefront does **not** choose a
 relays whatever item uuid `GET /v2/bundles/{uuid}` returns (`bundleItems.item.uuid`). The
 `catalogId = 1` filter runs **only** on standalone item search (`genericApi.ts`, `FilterApi.ts`,
 `translatedSearchApi.ts`), **never** on bundles. So a folded `BundleItems.itemId` makes **every new
-checkout of that kit POST the Agilant item** — a fresh wrong-catalog order each time. **The fix is
-data (restore `BundleItems`); the frontend needs no change.** Storefront-side detail:
+checkout of that kit POST the Agilant item** — a fresh wrong-catalog order each time. **The fix
+surface is the DB bundle rows PLUS the serving cache (below) — never the frontend code.**
+Storefront-side detail:
 [bundle item visibility & selectability](../../../2.0/apps/toga2-commerce/features/bundle-item-visibility-and-selectability.md).
 
+## Restoring `BundleItems` is NOT enough — a stale bundle cache kept minting bad orders
+Even **after** `BundleItems.itemId` was restored in the DB (bundle 17 → item 2157, bundle 15 →
+2158, verified), **new** Compass storefront orders **still** came in on the Agilant twin. Proof:
+order **SA136874** (created 2026-09-02 13:03:16 by user **83091**) — its incoming
+`POST /v2/sales-orders` in `Logs_Compass.Api` carried the **Agilant** item 2427 uuid
+(`88bd4bb2…`), not the Compass 2157 uuid — while the DB bundle already pointed at 2157.
+**SA136868** (11:25) showed the same. Because **multiple distinct users** got the stale item, this
+is a **shared server-side cache** (the api2/`_underscore` response cache and/or a CDN in front of
+`/v2/bundles`), **not** a per-browser one — so the DB fix is invisible to shoppers until the cache
+is flushed. The developer invalidated the **front-end cache**, which stopped the new bad orders.
+**Durable rule: a catalog-fold reversal is not complete until the bundle/item cache is invalidated
+across every layer — front-end, api2/`_underscore` response cache, and any CDN in front of
+`/v2/bundles`.**
+
+**Operational sequence (do it in this order):**
+1. Fix the data (restore `BundleItems`, re-point stragglers — below).
+2. **Invalidate the bundle/item cache** (front-end + api2/`_underscore` + any CDN on `/v2/bundles`).
+3. Confirm new incoming `POST /v2/sales-orders` in `Logs_Compass.Api` stop carrying the Agilant uuid.
+4. **Only then re-enable vendor transmission (cron 2)** — otherwise it transmits the still-bad
+   post-fix orders.
+
 ## The NetSuite→TOGa sync is NOT the source of new cust-2 bad orders (suspect ruled out)
 The 1.0 NetSuite→TOGa TOGaSupply sync (`worker/crons/toga2/netsuite/`,
 `App_Api_Toga2::syncSalesOrderFromNetsuite`, `library/app/api/toga2.php` ~L752) writes **only the
@@ -172,6 +209,14 @@ rule still holds: `cust 2` → catalog 1; `cust 1` and `cust 3` → catalog 2.
   nothing. Restore `BundleItems` to stop new wrong-catalog checkouts. (The sync still *creates
   items* in catalog 2 — that is the original duplicate-item source, see the
   [two-catalog item model](../features/item-catalogs-and-duplicate-items.md).)
+- **The reversal is NOT complete until the bundle/item cache is invalidated.** After `BundleItems`
+  was restored in the DB, new cust-2 checkouts kept POSTing the Agilant uuid because a **shared
+  server-side cache** (api2/`_underscore` response cache and/or a CDN in front of `/v2/bundles`)
+  still served the stale bundle — proven by two different users (SA136868, SA136874) getting the same
+  stale item after the DB fix. Sequence: fix data → **invalidate cache (front-end + api2/`_underscore`
+  + any CDN on `/v2/bundles`)** → confirm incoming `/v2/sales-orders` POSTs stop carrying the Agilant
+  uuid → **only then re-enable cron 2**. The fix surface is the DB bundle rows **plus** the serving
+  cache — never the frontend code.
 - **Never `UPDATE IGNORE` + delete-leftover for a catalog operation** — it permanently deletes
   collision rows and cannot be reversed. Use FK-checks-ON, fail-loud, single transaction.
 
@@ -207,6 +252,21 @@ catalog-1 items were folded into catalog-2 **AND** storefront/transmit depends o
 NULL-`assetType` order lines alone are **not** damage (Prudential and Quad show that as normal).
 
 ## Change history
+- 2026-09-02 — **CRITICAL: restoring `BundleItems` in the DB was not enough — a stale shared bundle
+  cache kept minting bad orders.** After the DB bundle rows were restored (bundle 17 → 2157, 15 →
+  2158), new cust-2 checkouts still POSTed the Agilant uuid: order SA136874 (13:03, user 83091) and
+  SA136868 (11:25) each carried the Agilant 2427 uuid on the incoming `/v2/sales-orders` while the DB
+  bundle already pointed at 2157. Two different users → a **shared server-side cache** (api2/
+  `_underscore` response cache and/or a CDN in front of `/v2/bundles`), not per-browser; the developer
+  invalidated the front-end cache to stop it. Added the rule that a fold reversal is incomplete until
+  the bundle/item cache is invalidated across every layer, and the operational order (fix data →
+  invalidate cache → confirm POSTs clean → only then re-enable cron 2). Extended the straggler cleanup
+  into the full by-id pattern for broken-window orders (re-point `SalesOrderItems.itemId`
+  Agilant-twin→Compass-twin, `PurchaseOrderItems.vendorItemId`+cost to the Compass VendorItem, clear
+  `PurchaseOrders.dtSubmitted` so cron 2 re-transmits): 2427→2157 / VI 3597 / SKU 5775600 / $945.17,
+  2431→2158 / VI 3598 / SKU 7761063 / $945.17; PO VI 3845→3597 @945.17, 3884→3600 @1627.38; orders
+  fixed 50312344-1, 50312409-1, SA136868, SA136874 + the earlier 5 pending
+  (SA136819/820/845/852/862). (jcardinal)
 - 2026-09-02 — **Completed the reversal and root-caused the rest of the incident.** Recorded that
   the first reversal was **incomplete** — it restored `Items`/`VendorItems`/`VendorItemCosts` and
   re-pointed only `customerId = 2` `SalesOrderItems`, leaving **10 tables** folded (cust-1/cust-3

package/package.json

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