toga-ai 1.0.739 → 1.0.740

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

@@ -3,7 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [TOGa Commerce (toga2-commerce / commerce2-react) Architecture](architecture.md) | `toga2-commerce` (npm package name **`commerce2-react`**, product name **TOGa Commerce**) is the customer-facing **B2B commerce storefront** of the 2.0 platform | src/main.tsx, src/App.tsx, src/routes.tsx, src/contexts/AuthContext.tsx, src/contexts/helpers/getLoginSettings.ts, src/api/axiosInstance.ts, src/stores/, src/themeConfig/ThemeContext.tsx, src/fieldsConfig/index.ts, src/hooks/useAssignClientFields.ts, vite.config.ts, package.json |
-| [Bundle item visibility & selectability (the three flags, and why they are enforced nowhere but the client)](features/bundle-item-visibility-and-selectability.md) | Which components of a kit a shopper can see and choose is decided **entirely in the browser**. | toga2-commerce/src/pages/BundleView/api/BundleApi.tsx, toga2-commerce/src/pages/BundleView/helpers/formatOriginalBundleData.ts, toga2-commerce/src/pages/BundleView/helpers/formatBundleToAddToCart.ts, toga2-commerce/src/pages/BundleView/hooks/useBundleEditFromLocalStorage.ts, toga2-commerce/src/stores/useBundleBuilderZu.ts, _underscore/Model/Client/BundleItem.php, _underscore/Model/Client/SalesOrderItem.php, api2/Component/Api/V2/V2.php |
+| [Bundle item visibility & selectability (the three flags, and why they are enforced nowhere but the client)](features/bundle-item-visibility-and-selectability.md) | Which components of a kit a shopper can see and choose is decided **entirely in the browser**. | toga2-commerce/src/pages/BundleView/api/BundleApi.tsx, toga2-commerce/src/pages/BundleView/helpers/formatOriginalBundleData.ts, toga2-commerce/src/pages/BundleView/helpers/formatBundleToAddToCart.ts, toga2-commerce/src/pages/BundleView/hooks/useBundleEditFromLocalStorage.ts, toga2-commerce/src/api/helpers/formatBundlesForSalesQuoteZuCartinEditCart.ts, toga2-commerce/src/api/genericApi.ts, toga2-commerce/src/api/FilterApi.ts, toga2-commerce/src/api/translatedSearchApi.ts, toga2-commerce/src/stores/useBundleBuilderZu.ts, _underscore/Model/Client/BundleItem.php, _underscore/Model/Client/SalesOrderItem.php, api2/Component/Api/V2/V2.php |
 | [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 Order-Total & Shipping Computation](features/cart-order-total-computation.md) | The Cart summary section (subtotal / shipping / tax / total) is **data-driven** from `cartData`. | toga2-commerce/src/pages/Cart/viewModel/useCartViewModel.ts, toga2-commerce/src/pages/Cart/CartPage.tsx, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/api/CartApi.ts |

package/knowledge/2.0/apps/toga2-commerce/features/bundle-item-visibility-and-selectability.md

@@ -6,13 +6,17 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-08-27
-owners: ["apeterson"]
+updated: 2026-09-02
+owners: ["apeterson", "jcardinal"]
 files:
   - toga2-commerce/src/pages/BundleView/api/BundleApi.tsx
   - toga2-commerce/src/pages/BundleView/helpers/formatOriginalBundleData.ts
   - toga2-commerce/src/pages/BundleView/helpers/formatBundleToAddToCart.ts
   - toga2-commerce/src/pages/BundleView/hooks/useBundleEditFromLocalStorage.ts
+  - toga2-commerce/src/api/helpers/formatBundlesForSalesQuoteZuCartinEditCart.ts
+  - toga2-commerce/src/api/genericApi.ts
+  - toga2-commerce/src/api/FilterApi.ts
+  - toga2-commerce/src/api/translatedSearchApi.ts
   - toga2-commerce/src/stores/useBundleBuilderZu.ts
   - _underscore/Model/Client/BundleItem.php
   - _underscore/Model/Client/SalesOrderItem.php
@@ -116,8 +120,28 @@ Also decided: **delete** the dead `where` clause in `BundleApi.tsx` rather than
 engine cannot prune nested children via `where` at all, and the clause could not express the
 fee / child-bundle exceptions even if it worked.
 
+## The bundle path never filters by catalog — it relays whatever item the API returns
+
+The storefront applies a `catalogId = 1` filter **only** on standalone item search
+(`src/api/genericApi.ts`, `FilterApi.ts`, `translatedSearchApi.ts`). The **bundle** path does not:
+`GET /v2/bundles/{uuid}` returns each kit line's `bundleItems.item.uuid`, and the cart submit relays
+that uuid verbatim (`src/api/helpers/formatBundlesForSalesQuoteZuCartinEditCart.ts`,
+`BundleView/api/BundleApi.tsx`). So the item a kit checkout POSTs is **whatever `BundleItems.itemId`
+resolves to on the server** — the browser never re-picks a catalog for it.
+
+**Consequence:** if a kit's `BundleItems.itemId` points at the wrong-catalog item, **every checkout
+of that kit silently POSTs the wrong item, and no frontend change fixes it — the data must be
+corrected.** This was the ongoing source of *new* bad orders after Compass USA's 2026-08-31 catalog
+fold: `BundleItems.itemId` for 434 active rows across 110 bundles still pointed at the Agilant
+catalog-2 twins, so each new kit checkout POSTed the Agilant item. Root cause + the
+restore-`BundleItems` fix:
+[Compass catalog-fold reversal](../../../clients/compass-usa/workflows/catalog-fold-reversal.md).
+
 ## Gotchas / known issues
 
+- **⚠ A folded/wrong `BundleItems.itemId` is invisible to the storefront's catalog filter.** The
+  catalog filter guards standalone search only; bundles relay the server's item uuid. Fix wrong-item
+  kits in the data (`BundleItems`), not in the frontend.
 - **⚠ Never read a flag on a `BundleItems` row without first knowing its row type.** Fee rows are
   invisible-but-mandatory; child-bundle rows are inactive-by-convention.
 - **⚠ Do not add a `where` to a uuid'd GET expecting nested filtering.** It is doubly inert (READ
@@ -145,6 +169,13 @@ direct API write (`Logs.Api` request payload for that order).
 
 ## Change history
 
+- 2026-09-02 — Recorded that the storefront's `catalogId = 1` filter guards **standalone item
+  search only** (`genericApi.ts`, `FilterApi.ts`, `translatedSearchApi.ts`); the **bundle** path
+  relays whatever `bundleItems.item.uuid` `GET /v2/bundles/{uuid}` returns, so a kit checkout POSTs
+  whatever `BundleItems.itemId` resolves to server-side. A wrong-catalog `BundleItems.itemId`
+  therefore silently POSTs the wrong item and can only be fixed in data — this was the ongoing
+  source of new bad Compass orders after the 2026-08-31 catalog fold (434 rows / 110 bundles still
+  on the Agilant twins). (jcardinal)
 - 2026-08-27 — Created from an investigation-only session (no code changed) into how part number
   `S24D402GAN` reached Compass USA order `SA136441`. Recorded that the bundle fetch's
   `BundlesItems.isActive` `where` clause in `BundleApi.tsx` has **never executed** (uuid'd GET

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

@@ -22,7 +22,7 @@
 | [Compass Sales-Order Line-Number Renumbering (and why it hangs off the SO hooks)](features/sales-order-line-renumbering.md) | 2.0 | Compass sales-order lines must stay numbered **1..N with no gaps** after any add, edit, or delete — downstream MITS/PO linking reads `lineNumber` as an identity | _underscore/Model/Compass/SalesOrderItem.php, _underscore/Model/Compass/SalesOrder.php |
 | [Stranded Approval Reassignment (repointing approvals off dead duplicate Compass Users rows)](features/stranded-approval-reassignment.md) | 2.0 | A Compass employee who leaves and comes back after more than `CONTACT_UNLINK_GRACE_DAYS` (5) is **inserted as a brand-new `Users` row** by the PEOPLE importer i | _underscore/Model/Compass/ApprovalDecision.php, worker2/Worker/Client/Compass/ApprovalReassignment.php, worker2/Worker/Client/Compass/PeopleFile.php |
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |
-| [Compass USA — reversing the 199-item catalog fold (MITS outage recovery)](workflows/catalog-fold-reversal.md) | 2.0 | The **root cause** of the Compass MITS transmission outage (the `assetType`-NULL and duplicate-vendor symptoms) was an ad-hoc cross-client **duplicate-items mer | test/team/2.0 deployment/duplicate_items_merge_ALL_CLIENTS.sql, test/team/2.0 deployment/duplicate_items_merge_analysis.sql, worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/common_sync_togasupply.php |
+| [Compass USA — reversing the 199-item catalog fold (MITS outage recovery)](workflows/catalog-fold-reversal.md) | 2.0 | The **root cause** of the Compass MITS transmission outage (the `assetType`-NULL and duplicate-vendor symptoms) was an ad-hoc cross-client **duplicate-items mer | test/team/2.0 deployment/duplicate_items_merge_ALL_CLIENTS.sql, test/team/2.0 deployment/duplicate_items_merge_analysis.sql, worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/common_sync_togasupply.php |
 | [Compass Cross-Kit Bundle Corruption — Detection & Repair](workflows/cross-kit-bundle-corruption.md) | 2.0 | A frontend regression in `toga2-commerce`'s edit-order bundle submission mis-attributed bundle (kit) line items and **fees/warranties** to the **wrong kit**, pe | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts |
 | [Granting a Compass user the same toga25-supply navigation as another user (role vs. SurfaceOverride)](workflows/granting-navigation-access.md) | 2.0 | "Give user X the same menu items user Y has" is the **navigation analog** of the recurring [bundle/persona grant](./granting-persona-bundle-access.md) request. | dbchanges2/Client_Compass/2026-08-12a - NavigationRoleGrants.sql, dbchanges2/Client_Compass/2026-02-25 - AgilantUsersViewAccess.sql, dbchanges2/Client_Compass/2026-08-11 - CompassODPViewVendorItemsAccess.sql, dbchanges2/Core/2026-08-12a - NavigationSurfaceSeed.sql |
 | [Granting a Compass user access to a bundle (persona grant) and the SuperUser role](workflows/granting-persona-bundle-access.md) | 2.0 | "Give user X sight of kit N" is a **recurring** Compass request, usually paired with "and make them a super user". | dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql |

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

@@ -6,7 +6,7 @@ project: Library
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-09-01
+updated: 2026-09-02
 owners: ["bala", "jcardinal"]
 files:
   - library/app/api/toga2.php
@@ -124,14 +124,18 @@ Plus `-1` / `-2` suffixed copies: items **2431, 2432, 2443, 2653**.
   span more than one catalog.** It matters only as a thing to re-check, because a part-number lookup
   with no catalog filter has **no ambiguity check on its exact-match branch**
   ([850 line-item resolution](odp-edi-850-item-resolution.md)).
-  **⚠ Unresolved tension — reconcile before relying on "partNumber is unique."** The
-  [2026-08-31 catalog-fold reversal](../workflows/catalog-fold-reversal.md) is recorded as having
-  folded **199 catalog-1 items into their catalog-2 Agilant canonical by `UPPER(partNumber)`**,
-  which requires those 199 to have shared a part number across the two catalogs pre-merge, and the
-  reversal restored them. That does not square with "zero part numbers span two catalogs" verified
-  the same day. Confirm on prod whether the restored catalog-1 twins carry **distinct** part numbers
-  (e.g. the `#B1H` / `-S` variant forms above) or genuinely-shared ones before treating table-wide
-  `partNumber` uniqueness as settled.
+  **Resolved: the twins carry DISTINCT part-number variants, so table-wide `partNumber` uniqueness
+  holds.** The Agilant `#ABA` form never equals the plain part number (e.g. `C40QYUC#ABA` vs
+  `C40QYUC`; `B7HJ2UC#ABA` vs `B7HJ2UC`), so any `UPPER(partNumber)` or partNumber-twin match
+  silently misses them. That is exactly why the
+  [catalog-fold reversal](../workflows/catalog-fold-reversal.md) ultimately mapped dupe→canon by
+  **primary key** from the pre-merge snapshot, never by part number, and why the `#ABA` PO-line
+  stragglers needed a manual VendorItem re-map. Only a history question remains (how the original
+  merge's `UPPER(partNumber)` partition folded pairs that do not share a part number); nothing
+  downstream depends on it. **⚠ Note:** the exact item ids ↔ catalog assignments in the
+  duplicate-pairs table above predate the 2026-08-31 fold and its reversal (which deleted then
+  restored catalog-1 items by their original snapshot ids), so re-read specific ids from current prod
+  before relying on them.
 
 ## Filtering by catalog: fine for *display*, never for *resolution*
 
@@ -196,6 +200,13 @@ children" rule:
 - **⚠ A NULL `catalogId` is a real state** (27 items in prod, 22 ODP `VendorItems` point at such
   items). Anything joining through `Catalogs` **drops those rows silently** — an inner join to
   `Catalogs` is itself a filter.
+- **⚠ `BundleItems.itemId` is a silent catalog-resolution consumer — the storefront never
+  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
+  [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
   copy; the flag's home catalog is not an accident. See
   [isFulfillable data quality & the type rule](isfulfillable-data-quality-and-type-rule.md).
@@ -212,6 +223,15 @@ children" rule:
   [catalog-fold reversal](../workflows/catalog-fold-reversal.md).
 
 ## Change history
+- 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
+  reversal maps dupe→canon by **primary key**, never by part number (part-number matching misses the
+  `#ABA` stragglers). Flagged that exact item ids ↔ catalog assignments in the duplicate-pairs table
+  predate the fold+reversal and should be re-read from prod. Added `BundleItems.itemId` as a silent
+  catalog-resolution consumer — the storefront relays the bundle item uuid with no catalog filter, so
+  a folded `BundleItems.itemId` (434 rows / 110 bundles) POSTs the wrong item on every kit checkout
+  until the data is fixed. (jcardinal)
 - 2026-09-01 — Folded in the **customer → catalog rule** (`customerId = 2` → catalog 1, everyone
   else → catalog 2; verified 182,787 vs 1 pre-merge) and the mandatory `customerId` scope on any
   catalog re-point (an unscoped one moved 687 Office-Depot lines). Added that the NetSuite sync

package/knowledge/clients/compass-usa/features/mits-po-transmission-to-vendors.md

@@ -5,8 +5,8 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-07-14
-owners: ["rgirish", "bala"]
+updated: 2026-09-02
+owners: ["rgirish", "bala", "jcardinal"]
 files:
   - worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php
   - worker/crons/toga2/compasscanada/workflow/2_transmit_mits_purchase_orders_to_vendors.php
@@ -14,6 +14,8 @@ files:
 related:
   - mits-po-to-so-item-linking.md
   - order-lifecycle-and-data-integrity.md
+  - item-catalogs-and-duplicate-items.md
+  - ../workflows/catalog-fold-reversal.md
 ---
 
 ## Summary
@@ -87,6 +89,19 @@ Compass Canada has a parallel `compasscanada/workflow/2_transmit_...` keyed on
 `CUSTOMER_ID__COMPASS_CANADA`.
 
 ## Gotchas / known issues
+- **⚠ Everything transmitted is sourced from the `VendorItem` the PO line points at — a
+  wrong-catalog `vendorItemId` sends the wrong SKU, wrong cost, AND the wrong channel.** The vendor
+  SKU and the cXML-vs-EMAIL routing come entirely from the `VendorItem` that
+  `PurchaseOrderItems.vendorItemId` references (with `PurchaseOrderItems.cost` for price). So a PO
+  line pointing at an **Agilant** VendorItem instead of the Office-Depot one transmits Agilant's
+  **internal SKU** and **wrong cost**, and — because that VendorItem carries **no
+  `overridePoSubmissionIntegrationId`** — falls back to the vendor's default **EMAIL** integration
+  instead of **cXML**. Verified in the legacy `Logs.API`: good order **SA136666** went **cXML** to
+  `b2b.odpbusiness.com` with `SupplierPartID 5775600` / `UnitPrice 945.17`; bad order **SA136846**
+  went **email** with `C40QYUC#ABA` / `$61`. This was a downstream symptom of the 2026-08-31 catalog
+  fold (a folded PO line resolved to the Agilant twin) — root cause and reversal:
+  [catalog-fold reversal](../workflows/catalog-fold-reversal.md);
+  [two-catalog item model](item-catalogs-and-duplicate-items.md).
 - **Item-less PO is silently marked submitted without being sent (the "logs show not sent
   but dtSubmitted is set" symptom).** The `dtSubmitted = NOW()` UPDATE runs **unconditionally
   after** the per-integration `foreach`, not inside it. If a PO has **zero
@@ -109,6 +124,12 @@ Compass Canada has a parallel `compasscanada/workflow/2_transmit_...` keyed on
   `dtSubmitted` stamped without a log (separate, previously-observed failure mode).
 
 ## Change history
+- 2026-09-02 — Recorded that cron 2 sources the vendor **SKU, cost, and cXML-vs-EMAIL routing**
+  entirely from the `VendorItem` at `PurchaseOrderItems.vendorItemId` (plus `PurchaseOrderItems.cost`),
+  so a PO line folded onto an **Agilant** VendorItem transmits Agilant's internal SKU, the wrong
+  cost, and — lacking `overridePoSubmissionIntegrationId` — drops from cXML to the default EMAIL
+  channel. Evidence: good `SA136666` cXML `SupplierPartID 5775600` / `945.17`; bad `SA136846` email
+  `C40QYUC#ABA` / `$61`. Downstream symptom of the 2026-08-31 catalog fold. (jcardinal)
 - 2026-07-14 — Fixed the emailed-PO PDF for both US Compass and Compass Canada: line-item
   rows now advance by their measured wrapped height (long descriptions no longer overwritten),
   and pagination is height-aware (a real 21-item PO went from a broken 17-page PDF to a clean

package/knowledge/clients/compass-usa/features/mits-sales-order-transmission-alerting.md

@@ -5,7 +5,7 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-08-31
+updated: 2026-09-02
 owners: ["dfranks", "bala", "jcardinal"]
 files:
   - worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php
@@ -125,7 +125,12 @@ backlog (0 new, several >24h, one ~20 days old).
    order**. This was the active blocker (e.g. item `4U555A-S`; ~10 distinct NULL-assetType
    items blocked 9 of 11 pending orders).
 2. **HTTP 403 `SalesOrder:Exists`** — MITS already created the order on a prior attempt, but
-   our side never recorded `c_dtTransmittedToCompass`, so the cron **retries it forever**.
+   our side never recorded `c_dtTransmittedToCompass`, so the cron **retries it forever**. **Now
+   handled (2026-09-02):** on a 403 `SalesOrder:Exists` the cron stamps
+   `SalesOrders.c_dtTransmittedToCompass`, writes a `Record`, and **continues** to the next order
+   instead of throwing — so an already-created order no longer starves the queue. Root cause of the
+   original loop (why we never stamped the first time) was the `App_ApiTransaction` decode fatal —
+   see the gotcha below.
 
 **Deeper root cause of the 2026-08-31 outage — a wrong catalog merge, not just missing data.**
 The NULL-assetType items were largely created by an ad-hoc cross-client dedup that folded
@@ -170,7 +175,19 @@ pages even when the count is under threshold. See
   console, pushed to ClickUp, and emailed — so the payload was deliberately removed. Alerts here
   name the order, not the person. (This is precisely what Canada still does wrong.)
 - **The MITS crons hold their API credentials inline in the file.** Treat both files as
-  secret-bearing when copying snippets anywhere (tickets, PR bodies, knowledge docs).
+  secret-bearing when copying snippets anywhere (tickets, PR bodies, knowledge docs). The two
+  hardcoded MITS credentials live inline in
+  `1_transmit_compass_sales_orders_to_mits.php` — note their location, never paste the values.
+- **⚠ 1.0 `App_ApiTransaction` built with `ENCODE_JSON` returns an ALREADY-DECODED object — do
+  NOT `json_decode()` it.** A transaction constructed with `App_ApiTransaction::ENCODE_JSON` hands
+  back a decoded object from `execute()`, not a JSON string. Calling `json_decode()` on it raises a
+  PHP 7.2 `"expects parameter 1 to be string, object given"` warning, which `App_Error` escalates to
+  a **FATAL**. In `1_transmit_compass_sales_orders_to_mits.php` that fatal fired **after** the order
+  transmitted to MITS but **before** stamping `c_dtTransmittedToCompass` — producing a ~42-order
+  backlog and the endless `SalesOrder:Exists` retry loop above (MITS kept the created order, we
+  never recorded it). Correct pattern:
+  `$decodedResp = is_string($resp) ? json_decode($resp) : $resp;`. This is a reusable 1.0 footgun,
+  not a Compass-only one — any `App_` code that `json_decode()`s an `ENCODE_JSON` response hits it.
 - **The transmit item query's `GROUP BY SalesOrderItems.id` hides false "duplicates."** In
   `1_transmit_compass_sales_orders_to_mits.php` (~L178-251, `GROUP BY` at L247) the
   `GROUP BY SalesOrderItems.id` collapses the `LEFT JOIN VendorItems` / `LEFT JOIN
@@ -193,6 +210,15 @@ pages even when the count is under threshold. See
   when this issue next fires. Watch that run rather than assuming it works.
 
 ## Change history
+- 2026-09-02 — **Shipped HTTP 403 `SalesOrder:Exists` handling** in
+  `1_transmit_compass_sales_orders_to_mits.php`: on that response the cron now stamps
+  `c_dtTransmittedToCompass`, writes a `Record`, and continues instead of throwing forever (which
+  had starved the `ORDER BY RAND()` queue). Recorded the **root cause** of the loop — a 1.0
+  `App_ApiTransaction` built with `ENCODE_JSON` returns an **already-decoded object**, so a
+  `json_decode()` on it raises a PHP 7.2 warning that `App_Error` escalates to a **FATAL** *after*
+  transmit but *before* the stamp, producing a ~42-order backlog and the endless retry loop; the
+  fix is `is_string($resp) ? json_decode($resp) : $resp`. Flagged it as a reusable 1.0 footgun. Also
+  noted the two hardcoded MITS credentials' location. (jcardinal)
 - 2026-09-01 — Traced the 2026-08-31 outage to its **deeper root cause**: an ad-hoc
   cross-client dedup folded Compass's 199 catalog-1 store items into their Agilant canonical, so
   order lines resolved to unclassified Agilant items (HTTP 400) and their fused VendorItems

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

@@ -19,7 +19,7 @@ project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-09-01
+updated: 2026-09-02
 owners: [jcardinal, bala, tcox, apeterson, dfranks, akhokhani]
 files: []
 related:
@@ -92,6 +92,12 @@ separate, related client (see its own profile).
   corrupted in `Client_Compass.SalesOrderItems` (Canada and Quad: zero). The code fix is
   preventive; existing rows still need a DB data-fix. Detection query + remediation plan:
   [Cross-Kit Bundle Corruption](workflows/cross-kit-bundle-corruption.md).
+- **⚠ A folded `BundleItems.itemId` makes the storefront POST the wrong-catalog item (2026-09-02).**
+  The storefront relays whatever item `GET /v2/bundles/{uuid}` returns and filters `catalogId = 1`
+  only on standalone search, never on bundles — so after the 2026-08-31 catalog fold, 434 kit-line
+  rows across 110 bundles still on the Agilant twins produced a fresh bad order on every kit
+  checkout. Fixed by restoring `BundleItems` in the complete catalog-fold reversal (fix is data, not
+  frontend): [catalog-fold reversal](workflows/catalog-fold-reversal.md).
 
 ## Vendors & integrations
 - **Office Depot (ODP)** — vendor id 1. ASNs arrive via **cXML** (direct V2 API) and via the

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

@@ -5,17 +5,20 @@ project: _Underscore
 client: compass-usa
 type: workflow
 status: active
-updated: 2026-09-01
+updated: 2026-09-02
 owners: ["jcardinal", "bala"]
 files:
   - test/team/2.0 deployment/duplicate_items_merge_ALL_CLIENTS.sql
   - test/team/2.0 deployment/duplicate_items_merge_analysis.sql
   - worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php
+  - worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php
   - library/app/api/toga2.php
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
 related:
   - ../features/item-catalogs-and-duplicate-items.md
   - ../features/mits-sales-order-transmission-alerting.md
+  - ../features/mits-po-transmission-to-vendors.md
+  - ../../../2.0/apps/toga2-commerce/features/bundle-item-visibility-and-selectability.md
   - ../../../1.0/apps/worker/workflows/netsuite-duplicate-items-dedup.md
 ---
 
@@ -59,48 +62,116 @@ NULL-catalog junk items** and **199 duplicate-Agilant items** (from the NetSuite
 inventory-adjustment item-create bug). **Only the 199 catalog-1 → catalog-2 folds were the
 damage.**
 
-**⚠ Open contradiction — not resolved, do not assume either side.** Folding by
-`UPPER(partNumber)` requires those 199 pairs to have **shared a part number across catalogs**
-pre-merge, and the reversal restored them. But a prod check of `Client_Compass` on **2026-09-01**
-found **zero part numbers duplicated at all, and zero spanning more than one catalog**. Both
-statements cannot be true of prod today. Re-check on prod whether the restored catalog-1 twins
-carry **distinct** part-number variants (the `#B1H` / `-S` forms) or genuinely-shared ones before
-relying on either the 199 figure or table-wide `partNumber` uniqueness. Same flag from the other
-side: [two-catalog item model](../features/item-catalogs-and-duplicate-items.md).
-
-## The reversal playbook (durable)
-
-1. **Restore a pre-merge snapshot as a scratch DB** — e.g. `Client_Compass_20260831_120000`
-   (taken ~12:00, before the ~12:43 merge). **Validate it is pre-merge**: catalog-1 twins
-   present, `customerId = 2` lines on catalog 1.
-2. **Rebuild the merge's damage map from the snapshot** — the Agilant-preferred ranking above,
-   filtered to `dupe.catalog = 1 AND canon.catalog = 2` = the 199.
-3. **Write a set-based, single-transaction, FK-checks-ON, NO `IGNORE`, COMMIT-left-commented
-   script** (`SNAP_DB.` / `TARGET_DB.` qualifiers) that:
-   - Restores the 199 Compass `Items` + their `VendorItems` / `VendorItemCosts` **by id**
-     (`NOT EXISTS` guard).
-   - **Re-points current `customerId = 2` `SalesOrderItems`** from the Agilant canonical back
-     to the Compass twin — **on CURRENT data, not a uuid-restore.** The sync re-created order
-     lines with **new uuids**, so restoring snapshot lines by uuid **collided 1062** on
-     `UNIQUE(salesOrderId, lineNumber)`.
-4. **Rehearse on a same-day full prod clone** — this run: ~49,267 re-points, 199 items, 0
-   orphans, held items 0-missing-assetType / 0-multi-vendor.
-5. **Apply to prod with a pre-run backup.** Result: queue drained to 0 pending; all
-   `customerId = 2` lines back on catalog 1.
-
-**CTO review gated this** (rehearse-on-clone, fail-loud, customer-scoped, tenant-locked).
+**Part-number matching is unreliable here — the reversal maps dupe→canon by PRIMARY KEY, not
+part number.** The Agilant twins carry **distinct** part-number variants, not shared ones: the
+`#ABA` form does not equal the Compass part number (`C40QYUC#ABA` = item 2216 vs Compass
+`C40QYUC` = 2157; `B7HJ2UC#ABA` = 2215 vs Compass `B7HJ2UC` = 2160). So any `UPPER(partNumber)`
+or partNumber-twin re-point silently misses them, which is why the complete reversal keys off the
+snapshot's own primary keys (below) and table-wide `partNumber` uniqueness still holds on prod.
+(Left open only as history: how the original merge's `UPPER(partNumber)` partition folded pairs
+that do not share a part number — the reversal does not depend on the answer, because it never
+matches on part number.) Same note from the other side:
+[two-catalog item model](../features/item-catalogs-and-duplicate-items.md).
+
+## The first reversal was INCOMPLETE — it left 10 tables folded
+
+The earlier reversal (`compass_twocatalog_fix.sql`) restored `Items` / `VendorItems` /
+`VendorItemCosts` and re-pointed **`SalesOrderItems`** — but **only the `customerId = 2` slice**
+of those. It **left folded** every other table the merge touched: `customerId = 1` and
+`customerId = 3` `SalesOrderItems` (~50k rows), `ItemFeatures`, `ItemImages`, **`BundleItems`**,
+`Personas_Items`, `Units`, `ItemPrices`, `ItemMedia`, `AssortmentItems`, and `InvoiceItems` — 10
+tables still pointing at the Agilant canonical.
+
+**Durable rule: a fold reversal MUST cover EVERY table the merge enumerates.** Restoring the
+parent `Items` and re-pointing one child table is not a reversal. The
+`duplicate_items_merge_ALL_CLIENTS.sql` block lists **38** reference points — read it as the
+checklist:
+
+- **24 `itemId` tables**,
+- **`Entitlements.saleItemId`**,
+- **3 `vendorItemId` tables** — `PurchaseOrderItems`, `VendorItemCosts`, `Personas_VendorItems`,
+- **10 `unitId` tables**.
+
+Anything on that list still resolving to a canonical is unreversed. The left-folded `BundleItems`
+in particular was the ongoing source of *new* bad orders (see below).
+
+## The complete reversal (durable method)
+
+Restore **every** fold-affected row from the pre-merge snapshot
+`Client_Compass_20260831_120000` (taken ~12:00, before the ~12:43 merge) **BY PRIMARY KEY** — not
+by part-number twin matching (the `#ABA` variants make that unreliable, see above). The snapshot's
+own primary keys are the only dependable dupe→canon mapping. **Validate the snapshot is pre-merge
+first** (catalog-1 twins present, `customerId = 2` lines on catalog 1). Then, in a single
+transaction, FK-checks-ON, **no `UPDATE IGNORE`**, COMMIT left commented (`SNAP_DB.` / `TARGET_DB.`
+qualifiers):
+
+1. **Parents — full-row restore.** `Items`, `VendorItems`, `VendorItemCosts`, `Units` restored
+   whole from the snapshot by id (`NOT EXISTS` guard).
+2. **Children — FK-column-only restore.** For every child table on the merge's 38-point list,
+   restore **only the folded FK column** to its snapshot value, keyed by the child row's own PK.
+   (Verified zero non-FK drift, so nothing else is touched.)
+3. **Post-snapshot "broken-window" rows** — rows created **after 2026-08-31 12:00** that are not
+   in the snapshot are re-pointed canon→dupe on **current** data, **scoped `customerId = 2`** (the
+   uuid-collision and customer-scope rules below still apply — the sync re-created order lines with
+   **new uuids**, so a uuid-restore collided 1062 on `UNIQUE(salesOrderId, lineNumber)`).
+4. **Verify byte-for-byte.** This run: **0** rows still folded across all **38** tables and **0**
+   byte mismatches over **208,845** compared rows.
+
+**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:
+[MITS PO transmission to vendors](../features/mits-po-transmission-to-vendors.md).
+
+## The folded `BundleItems` was the storefront's ongoing bad-order source
+`BundleItems.itemId` (kit definitions) still pointed at the Agilant catalog-2 twins — **434 active
+rows across 110 bundles**. The `toga2-commerce` storefront does **not** choose a catalog: it
+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:
+[bundle item visibility & selectability](../../../2.0/apps/toga2-commerce/features/bundle-item-visibility-and-selectability.md).
+
+## 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
+Agilant `customerId = 3` sales order** for Compass — it **pins** `locationId = 615286` and
+`customerId = 3` (~L807-809) and cannot write or re-point a `customerId = 2` (Compass storefront)
+order. **Stopping it fixed nothing.** The real ongoing source of new bad orders was the folded
+`BundleItems` (above), not the sync — this corrects the earlier "the sync re-points cust-2 lines
+back to Agilant / stop it first" concern. (The sync still *creates items* in catalog 2 — that is
+the original duplicate-item source, see the two-catalog model.)
+
+Context — the Compass order chain is up to **four** SalesOrders, linked by the
+`SalesOrders_PurchaseOrders` / `PurchaseOrders_SalesOrders` bridge tables: Compass storefront SO
+(`cust 2`) → MITS PurchaseOrder → ODP SO (`cust 1`) → Agilant/NetSuite SO (`cust 3`). The catalog
+rule still holds: `cust 2` → catalog 1; `cust 1` and `cust 3` → catalog 2.
 
 ## Critical rules
 
+- **Cover EVERY table the merge lists — restore by PRIMARY KEY, not by part number.** The merge
+  enumerates 38 reference points (24 `itemId` + `Entitlements.saleItemId` + 3 `vendorItemId` +
+  10 `unitId`); a reversal that touches only `Items` + one child table is incomplete (the first
+  attempt left 10 tables folded). `#ABA` twins share no part number, so partNumber matching misses
+  them — map dupe→canon from the snapshot's own PKs.
 - **Scope every catalog re-point by `customerId`.** An unscoped
   `UPDATE ... WHERE itemId = <agilantId>` wrongly moved **687 Office-Depot lines** onto the
   Compass item and had to be corrected.
-- **Re-point on CURRENT data, never restore order lines by uuid** — the sync minted new uuids,
-  so a uuid-restore collides on `UNIQUE(salesOrderId, lineNumber)` (1062).
-- **Stop the Compass NetSuite sync first.** The sync re-creates Compass order lines on Agilant
-  items, so the reversal is only durable if the sync is stopped; re-enabling risks re-pointing
-  new/re-synced orders back to Agilant (2 lines seen after a test re-enable). See the
-  [two-catalog item model](../features/item-catalogs-and-duplicate-items.md).
+- **Re-point post-snapshot rows on CURRENT data, never restore order lines by uuid** — the sync
+  minted new uuids, so a uuid-restore collides on `UNIQUE(salesOrderId, lineNumber)` (1062).
+- **The NetSuite→TOGa sync is NOT the ongoing source of new cust-2 bad orders — the folded
+  `BundleItems` is.** `syncSalesOrderFromNetsuite` pins `customerId = 3` for Compass and writes
+  only the Agilant-tier SO, so it cannot re-point a cust-2 storefront line; stopping it changes
+  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).)
 - **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.
 
@@ -136,6 +207,23 @@ 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 — **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
+  `SalesOrderItems` ~50k, `ItemFeatures`, `ItemImages`, `BundleItems`, `Personas_Items`, `Units`,
+  `ItemPrices`, `ItemMedia`, `AssortmentItems`, `InvoiceItems`). Added the **cover-every-table**
+  rule (the merge lists 38 reference points: 24 `itemId` + `Entitlements.saleItemId` + 3
+  `vendorItemId` + 10 `unitId`) and the **complete method**: restore every fold-affected row from
+  the pre-merge snapshot **by PRIMARY KEY** (part-number matching fails because `#ABA` twins carry
+  distinct part numbers), parents full-row / children FK-column-only, post-snapshot rows re-pointed
+  cust-2 on current data; verified 0 folded across 38 tables / 0 byte mismatches over 208,845 rows.
+  Recorded the folded **`BundleItems`** (434 rows / 110 bundles) as the storefront's ongoing
+  bad-order source (toga2-commerce relays the bundle item uuid with no catalog filter — fix is
+  data), the **`#ABA` straggler** manual VendorItem re-map (3845→3597 @945.17, 3884→3600 @1627.38,
+  scoped cust-2 pending PO lines + clear `dtSubmitted`), and that the **NetSuite→TOGa sync is not**
+  the source of new cust-2 orders (it pins `customerId = 3` + `locationId = 615286`, writes only the
+  Agilant SO) — correcting the earlier "stop the sync first" rule. Resolved the part-number
+  contradiction for the reversal (maps by PK, never by partNumber). (jcardinal)
 - 2026-09-01 — Flagged (did **not** resolve) the contradiction between this doc's 199
   shared-`UPPER(partNumber)` catalog-1→catalog-2 folds and the same-day prod verification that zero
   Compass part numbers span two catalogs; mirrored from the item-catalogs doc so it is visible from

package/package.json

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