toga-ai 1.0.720 → 1.0.722

package/knowledge/1.0/apps/worker/workflows/netsuite-duplicate-items-dedup.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: workflow
 status: active
-updated: 2026-08-31
+updated: 2026-09-01
 owners: [jcardinal]
 files:
   - library/app/api/toga2.php
@@ -14,6 +14,8 @@ files:
 related:
   - ../features/netsuite-togasupply-per-client-sync.md
   - ../../library/features/netsuite-suiteql-rest-shim.md
+  - ../../../clients/compass-usa/workflows/catalog-fold-reversal.md
+  - ../../../clients/compass-usa/features/item-catalogs-and-duplicate-items.md
 ---
 
 ## Summary
@@ -29,6 +31,16 @@ after the code fix is deployed.
 **Verified in prod (2026-08-31):** all **17** NetSuite clients now show **0 duplicate part numbers**
 (e.g. `Client_Nychh` 3954→1818 items, `Client_Canon` 913→425; 0 orphans, 0 collisions).
 
+> **⚠ CORRECTION (2026-09-01): "0 duplicate part numbers" is NOT proof of a clean run for a
+> multi-catalog client.** This merge is **catalog-blind** — it groups on `UPPER(partNumber)` only.
+> For **Compass**, the same part number **legitimately exists once per catalog** (catalog 1 =
+> store, catalog 2 = Agilant), so the merge folded **199 intentional catalog-1 store items into
+> their Agilant canonical**, broke MITS transmission platform-wide, and had to be reversed. Before
+> running this on any client, confirm the client is **single-catalog**; if not, the dedup must be
+> **catalog-aware** (dedup within a catalog, never across). See the Compass
+> [catalog-fold reversal](../../../clients/compass-usa/workflows/catalog-fold-reversal.md) and
+> [Compass item catalogs & duplicate items](../../../clients/compass-usa/features/item-catalogs-and-duplicate-items.md).
+
 ## Root cause — why the duplicates existed at all
 
 `syncInventoryAdjustmentFromNetsuite`'s item-create **omitted the catalog** that
@@ -90,9 +102,29 @@ duplicates** and must be deployed first — see
   **benign skip**, not a failed migration.
 - **A plain `UPDATE IGNORE` + delete-leftover is insufficient.** Dupe-vs-dupe unique-key collisions leave
   orphaned child FKs; only the survivor-per-key re-pointing (step 5) is correct.
+- **⚠ The merge is CATALOG-BLIND — it does NOT handle multi-catalog clients.** It groups on
+  `UPPER(partNumber)` only, with an Agilant-preferred canonical rule. For a client that keeps the same
+  part number in two intentional catalogs (Compass: store vs Agilant), it folds legitimate per-catalog
+  twins together and **destroys** the store items. Confirm a client is single-catalog before running;
+  otherwise make the dedup catalog-scoped. The Compass fold deleted 199 store items and broke MITS —
+  see the [catalog-fold reversal](../../../clients/compass-usa/workflows/catalog-fold-reversal.md).
+- **`UPDATE IGNORE ...; DELETE ... WHERE fk=dupe` permanently DELETES collision rows** and drops its
+  helper maps, so prod cannot self-reverse. A reversal needs a **pre-merge snapshot** restored as a
+  scratch DB — plan the backup before running any variant of this.
+- **Blast radius of the 2026-08-31 `duplicate_items_merge_ALL_CLIENTS.sql`:** it ran on 17 clients
+  (Masonite, Ncci, Erau, Shrss, Wmchealth, Trividiahealth, Prudential, Miamidade, Browardsheriff,
+  Nychh, Canon, Quad, Compass, Elite, Growrk, Spglobal, Endeavorhealth). At-risk = two-catalog +
+  TOGa Commerce clients like Compass; a **per-client assessment is outstanding**.
 
 ## Change history
 
+- 2026-09-01 — **⚠ Corrected the success claim.** "0 duplicate part numbers" is NOT a clean-run proof
+  for a multi-catalog client. This merge is catalog-blind (groups on `UPPER(partNumber)` only), so for
+  Compass it folded 199 intentional catalog-1 store items into their Agilant canonical, broke MITS
+  transmission platform-wide, and had to be reversed from a pre-merge snapshot. Added the
+  confirm-single-catalog precondition, the permanent-delete / no-self-reverse warning, and the
+  17-client blast radius with the outstanding per-client assessment. See the Compass
+  [catalog-fold reversal](../../../clients/compass-usa/workflows/catalog-fold-reversal.md). (jcardinal)
 - 2026-08-31 — Documented the one-time duplicate-`Items` dedup across all 17 NetSuite clients (recursive
   MERGE over ~23 `itemId` tables + `Entitlements.saleItemId`, `VendorItems`/`Units` FK cascades,
   survivor-per-key collision resolution), its root cause (the inventory-adjustment item-create omitted

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

@@ -16,7 +16,7 @@ project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-08-31
+updated: 2026-09-01
 owners: [jcardinal, bala, tcox, apeterson]
 files: []
 related:
@@ -190,4 +190,10 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   8 Manager. USA grants the fulfillment records to roles 3 + 7; Canada grants most of them to role 1
   only. Nearly every logged-in Canada user carries role 1, so this is usually invisible — but ~10
   users hold Compass Base without Base and still hit the gap.
+- **Canada was NOT damaged by the 2026-08-31 cross-client item merge, and is structurally
+  immune.** It was **not** in the `duplicate_items_merge_ALL_CLIENTS.sql` client list; it has a
+  **single catalog** ("compass"), 0 part numbers in multiple catalogs, and 0 duplicate part
+  numbers — because it does **not** use NetSuite, so it never hit the inventory-adjustment
+  dupe-item bug that fed the merge. The catalog-fold damage and reversal were Compass USA only.
+  See [Compass USA catalog-fold reversal](../compass-usa/workflows/catalog-fold-reversal.md).
 - Related: [Compass USA](../compass-usa/profile.md).

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

@@ -6,7 +6,7 @@
 | [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF) on the upstream SalesOrder. | _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Model/Compass/PurchaseOrder.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql, dbchanges2/Client_Compass/2026-06-15b - BackfillSA132781ItemFulfillmentTracking.sql, dbchanges2/Client_Compass/2026-06-16 - CleanupSA132763CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16b - CleanupSA132743CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16c - BackfillSA132763C40QYUCTracking.sql, dbchanges2/Client_Compass/2026-06-18a - CleanupSA132898DuplicateTracking.sql, dbchanges2/Client_Compass/2026-06-18b - CleanupSA132881DuplicateTracking.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql |
 | [Cost Centers — Unit Locations, numeric-only policy](features/cost-centers.md) | 2.0 | A Compass "cost center" — the value a user picks in commerce and that lands on an order — is **not** a `CostCenters` row. | toga2-commerce/src/pages/Cart/api/CartApi.ts, worker1.5/crons/toga2/compass/import_locations.php, _underscore/Model/Compass/SalesOrder.php, api2/Component/Api/V2/V2.php, dbchanges2/Client_Compass/2026-07-06 - RemoveNonNumericCostCenters.sql |
 | [Compass isFulfillable — Data Quality & the Type-Derived Rule](features/isfulfillable-data-quality-and-type-rule.md) | 2.0 | A **prod-data investigation (2026-08-12, read-only)** into why so many Compass storefront lines still have a dead **Qty Fulfilled** cell. | _underscore/Model/Client/Item.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/backfill_isfulfillable_all_clients.php, dbchanges2/Core/2026-07-17 - RegisterItemIsFulfillableInterceptors.sql, toga2-supply/src/pages/Orders/view/OrderView/components/sections/OrderItemsTableSection.tsx |
-| [Compass Item Catalogs (Compass vs Agilant) & the Duplicate Items the NetSuite Sync Creates](features/item-catalogs-and-duplicate-items.md) | 1.0 | `Client_Compass.Items` is **split across catalogs by which pipeline created the item**, and the two halves are routinely mistaken for one. | library/app/api/toga2.php, _underscore/Model/Compass/PurchaseOrder.php, _underscore/Model/Compass/Usa/PurchaseOrder.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |
+| [Compass Item Catalogs (Compass vs Agilant) & the Duplicate Items the NetSuite Sync Creates](features/item-catalogs-and-duplicate-items.md) | 1.0 | `Client_Compass.Items` is **split across catalogs by which pipeline created the item**, and the two halves are routinely mistaken for one. | library/app/api/toga2.php, _underscore/Model/Compass/PurchaseOrder.php, _underscore/Model/Compass/Usa/PurchaseOrder.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php |
 | [Compass: Item-Fulfillment TableViews (for-sales-order-items & for-sales-orders, tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | Two sibling Compass TableViews in `Client_Compass` display fulfilled items in toga2-supply, both driven by `TableViews` / `TableViewJoins` / `TableViewFields` c | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql, dbchanges2/Client_Compass/2026-06-11 - ItemFulfillmentsForSalesOrdersTableView.sql, dbchanges2/Client_Compass/2026-06-15a - FixItemFulfillmentTrackingNumberJoins.sql, dbchanges2/Client/2026-07-15a - ExcludeFeeItemsFromItemFulfillmentsForSalesOrdersView.sql |
 | [Compass MITS PO → SO Item Linking](features/mits-po-to-so-item-linking.md) | 2.0 | MITS sends Compass inbound Purchase Orders (`POST /v2/purchase-orders`) against a Sales Order (`mitsSalesOrder`). | _underscore/Model/Compass/PurchaseOrder.php, _underscore/Model/Compass/Usa/PurchaseOrder.php, api2/Component/Api/V2/V2.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |
 | [Compass MITS PO Transmission to Vendors](features/mits-po-transmission-to-vendors.md) | 2.0 | The 1.0 worker cron `2_transmit_mits_purchase_orders_to_vendors.php` transmits Compass PurchaseOrders to their vendors (Office Depot, Strategic Systems, Compass | 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, library/app/client/compass.php |
@@ -22,6 +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 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

@@ -7,19 +7,22 @@ client: compass-usa
 type: client-feature
 status: active
 updated: 2026-09-01
-owners: ["bala"]
+owners: ["bala", "jcardinal"]
 files:
   - library/app/api/toga2.php
   - _underscore/Model/Compass/PurchaseOrder.php
   - _underscore/Model/Compass/Usa/PurchaseOrder.php
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
   - worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php
+  - worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php
 related:
   - odp-edi-850-item-resolution.md
   - mits-po-to-so-item-linking.md
+  - mits-sales-order-transmission-alerting.md
   - isfulfillable-data-quality-and-type-rule.md
   - ../workflows/odp-duplicate-po-line-cleanup.md
   - ../workflows/odp-order-pipeline-to-netsuite.md
+  - ../workflows/catalog-fold-reversal.md
   - ../profile.md
   - ../../../1.0/apps/library/features/netsuite-item-isfulfillable-sync.md
   - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
@@ -62,6 +65,26 @@ the same list — they are **two different source systems' views** of overlappin
 (`vendorId = 1`) point at **catalog-2** items. Filtering the ODP item lookup to catalog 1 therefore
 breaks a large slice of the Office Depot pipeline outright.
 
+## Customer → catalog rule (which catalog an order resolves to)
+
+Confirmed by the developer and by pre-merge data (2026-08-31):
+
+- **`customerId = 2` (Compass) sales orders → catalog 1 (Compass/store) items.**
+- Everyone else — **Office Depot `customerId = 1`, Agilant `customerId = 3`** → catalog 2
+  (Agilant) items.
+
+Pre-merge snapshot: `customerId = 2` order lines were ~100% on catalog 1 (**182,787 vs 1**).
+The store (catalog-1) item is the one that carries the MITS classification
+(`assetType`/`category`/`type`); a Compass line that resolves to a catalog-2 Agilant item has
+NULL classification and **MITS rejects the whole order** (HTTP 400 "The AssetType field is
+required"). So this mapping is load-bearing.
+
+**⚠ Every catalog re-point MUST be scoped by `customerId`.** An ad-hoc
+`UPDATE ... WHERE itemId = <agilantId>` with no customer filter wrongly moved **687
+Office-Depot lines** onto a Compass item and had to be corrected. This is the durable lesson
+from the 2026-08-31 catalog-fold reversal — see
+[catalog-fold reversal](../workflows/catalog-fold-reversal.md).
+
 ## Where the "Agilant" catalog is hardcoded
 
 The 1.0 side writes and reads catalog 2 **by name**, in four places — none of them configurable:
@@ -93,13 +116,21 @@ Plus `-1` / `-2` suffixed copies: items **2431, 2432, 2443, 2653**.
 **Two distinct duplicate shapes, and only the first exists in prod today:**
 - **Different part numbers** (the table above) — the two rows never match on part number, so each
   pipeline keeps using "its own" item and quantities/fulfillments diverge. This is the live shape.
-- **Same part number, two catalogs — NOT present in prod.** This is the shape behind the
-  [dual-catalog duplicate PO-line bug](../workflows/odp-duplicate-po-line-cleanup.md) (4,886
+- **Same part number, two catalogs — NOT present in prod (2026-09-01).** This is the shape behind
+  the [dual-catalog duplicate PO-line bug](../workflows/odp-duplicate-po-line-cleanup.md) (4,886
   duplicate PO lines across 1,320 Office Depot POs when that was investigated).
   **Verified on prod `Client_Compass` 2026-09-01: zero part numbers are duplicated at all, and zero
   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.
 
 ## "Who changed this part number?" — the audit trail says nobody
 
@@ -143,8 +174,25 @@ children" rule:
 - **⚠ Do not "fix" a mismatch by creating an item** so a string matches. That is how the junk items
   got there in the first place — fix the `VendorItems` mapping instead
   ([850 line-item resolution](odp-edi-850-item-resolution.md)).
+- **The NetSuite sync UPDATE path never touches `assetType`/`category`/`type`.** `getCreateItem`
+  stamps them as NULL on create (so a **new** Agilant item is born unclassified → a Compass line
+  on it fails MITS), but the sync UPDATE only PUTs `inventoryType` / `isFulfillable`. Practical
+  consequence: once classification is set on an item it is **durable across sync runs** (the sync
+  will not revert it) — the exposure is only newly-created items. This is why a store-catalog data
+  repair survives, but the Compass NetSuite sync must still be **stopped before** any catalog
+  re-point (it re-creates Compass order lines on Agilant items). See
+  [catalog-fold reversal](../workflows/catalog-fold-reversal.md).
 
 ## Change history
+- 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
+  UPDATE path never touches `assetType`/`category`/`type` (so classification is durable once set;
+  only new items are born unclassified) and that the Compass sync must be stopped before a re-point.
+  Cross-linked the [catalog-fold reversal](../workflows/catalog-fold-reversal.md) and flagged an
+  **unresolved tension**: that reversal folded/restored 199 catalog-1 items by `UPPER(partNumber)`,
+  which implies shared cross-catalog part numbers pre-merge and does not square with the same-day
+  "partNumber is unique table-wide" verification — needs a prod re-check. (jcardinal)
 - 2026-09-01 — Recorded a **second, independent victim of the same catalog-scoping trap, on the 2.0
   side**: `_Model_Compass_PurchaseOrder::handleMrOrder` references MR sales-order items with a
   hardcoded `COMPASS_CATALOG_UUID` (`961dbcbc…` = catalog **1**), which is the mirror image of the

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

@@ -17,6 +17,8 @@ files:
   - dbchanges2/Logs/2026-08-04a - MITS rejection business recipients.sql
 related:
   - mits-po-transmission-to-vendors.md
+  - item-catalogs-and-duplicate-items.md
+  - ../workflows/catalog-fold-reversal.md
   - ../../compass-canada/profile.md
   - ../../../2.0/apps/worker2/features/error-escalation-cron.md
   - ../../../2.0/apps/_underscore/features/error-reporting-issue-event.md
@@ -125,9 +127,20 @@ backlog (0 new, several >24h, one ~20 days old).
 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**.
 
+**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
+Compass's **199 catalog-1 (store) items into their Agilant (catalog-2) canonical**, so Compass
+order lines resolved to Agilant items that have no store classification. The same merge fused
+their VendorItems, which is what triggered the SQL 1242 abort (see gotchas below). Full root
+cause + the reversal playbook: [catalog-fold reversal](../workflows/catalog-fold-reversal.md).
+Compass keeps two intentional catalogs and the customer→catalog rule is load-bearing — see
+[Compass item catalogs & duplicate items](./item-catalogs-and-duplicate-items.md).
+
 **Fix the data:** assign the correct `assetTypeId` to the affected `Client_Compass.Items`
 (business owns the mapping), and check whether the NetSuite item sync owns `assetType` — if it
-does, it will revert the fix unless the source is corrected too.
+does, it will revert the fix unless the source is corrected too. (Verified: the sync UPDATE path
+never touches `assetType`/`category`/`type`, so a set value is durable — but new items are born
+unclassified on the Agilant catalog. See the two-catalog doc.)
 
 **Recommended code hardening (NOT yet implemented):** wrap each order's transmit in
 `try/catch` so one MITS rejection raises the business issue but **continues to the next
@@ -158,6 +171,17 @@ pages even when the count is under threshold. See
   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).
+- **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
+  VendorItemCosts` fan-out to one row per line. Running that SELECT **without** the GROUP BY
+  shows FALSE duplicate fee lines (fees have 2 `VendorItemCosts` rows) — the real cron sends
+  one line per SalesOrderItem. Do not "diagnose" duplicates from the un-grouped query.
+- **`c_preferredVendorId` scalar subquery has no `LIMIT` → SQL 1242 on multi-vendor items.**
+  Any item with >1 active `VendorItem` makes that scalar subquery return >1 row and **aborts
+  the whole run**. This was the latent bug the catalog merge exposed (it fused VendorItems).
+  A one-line `ORDER BY VendorItems.id LIMIT 1` guard fixes it, but the proper two-catalog data
+  fix makes Compass items single-vendor so the guard is not needed.
 - **Adding a recipient does not turn ClickUp ticketing off.** Routing is both-and, not
   either-or: `_Worker_Infrastructure_Errors` runs `if ($recipients !== null)` and
   `if ((bool) $issue->createsClickupTask)` as **two independent** branches.
@@ -169,6 +193,14 @@ 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-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
+  tripped the transmit's un-`LIMIT`ed `c_preferredVendorId` scalar subquery (SQL 1242, whole run
+  aborts). Recorded the two transmit-query gotchas (`GROUP BY SalesOrderItems.id` hides false
+  duplicate fee lines from the VendorItemCosts fan-out; the `c_preferredVendorId` subquery needs
+  `ORDER BY VendorItems.id LIMIT 1` or single-vendor data). Cross-linked the new catalog-fold
+  reversal workflow and two-catalog item-model doc. (jcardinal)
 - 2026-08-31 — Diagnosed the recurring backlog's **root cause**: not volume but **poison-order
   starvation**. One MITS rejection `throw`s and aborts the whole run, and because the driver
   query uses `ORDER BY RAND()`, a stuck order blocks a random set of good orders every run.

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

@@ -31,6 +31,7 @@ related:
   - workflows/granting-persona-bundle-access.md
   - workflows/granting-navigation-access.md
   - features/mits-sales-order-transmission-alerting.md
+  - workflows/catalog-fold-reversal.md
   - features/asn-to-item-fulfillment.md
   - features/order-fulfillment-status-per-line.md
   - features/cost-centers.md

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

@@ -0,0 +1,120 @@
+---
+title: Compass USA — reversing the 199-item catalog fold (MITS outage recovery)
+framework: "2.0"
+project: _Underscore
+client: compass-usa
+type: workflow
+status: active
+updated: 2026-09-01
+owners: ["jcardinal"]
+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
+  - 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
+  - ../../../1.0/apps/worker/workflows/netsuite-duplicate-items-dedup.md
+---
+
+## Summary
+
+The **root cause** of the Compass MITS transmission outage (the `assetType`-NULL and
+duplicate-vendor symptoms) was an ad-hoc cross-client **duplicate-items merge** that wrongly
+folded Compass's **two intentional catalogs** together. This workflow records the damage and
+the **durable playbook** used to reverse it. See the
+[two-catalog item model](../features/item-catalogs-and-duplicate-items.md) for why the catalogs are
+intentional.
+
+## What broke (root cause)
+
+An ad-hoc merge run **2026-08-31 ~12:43** — `test/team/2.0 deployment/
+duplicate_items_merge_ALL_CLIENTS.sql`, Compass block lines **1201-1297**, committed — treated
+Compass's two catalogs as duplicates and folded **199 catalog-1 (store) items into their
+catalog-2 (Agilant) canonical**. Its canonical rule was **Agilant-preferred**:
+
+```
+ROW_NUMBER() OVER (PARTITION BY UPPER(partNumber)
+  ORDER BY (catalog='Agilant' AND manufacturerId IS NOT NULL) DESC,
+           (catalog='Agilant') DESC,
+           (manufacturerId IS NOT NULL) DESC, id)
+```
+
+For each of the ~35 reference tables it ran
+`UPDATE IGNORE <t> SET fk=canon WHERE fk=dupe; DELETE <t> WHERE fk=dupe;` — so **collision
+rows were permanently DELETED** — then `DELETE Items` on the Compass items. Its helper maps
+(`_merge_map` / `_unit_map` / `_vi_map`) were dropped, so **prod cannot self-reverse**.
+
+**Two failure signatures resulted:**
+1. Compass sales orders resolved to Agilant items lacking store classification
+   (`assetType`/`category`/`type`) → **MITS HTTP 400** "The AssetType field is required".
+2. The Agilant items now had **duplicate active VendorItems** (the merge fused them), so the
+   transmit's `c_preferredVendorId` scalar subquery returned **>1** → **SQL 1242**, aborting
+   the whole run.
+
+**Not all of the merge was damage.** Of 550 total deleted dupes it correctly removed **150
+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.**
+
+## 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).
+
+## Critical rules
+
+- **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).
+- **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.
+
+## Blast radius — other clients (OUTSTANDING)
+
+The `duplicate_items_merge_ALL_CLIENTS.sql` ran `USE Client_<X>` on **17 clients**: Masonite,
+Ncci, Erau, Shrss, Wmchealth, Trividiahealth, Prudential, Miamidade, Browardsheriff, Nychh,
+Canon, Quad, **Compass**, Elite, Growrk, Spglobal, Endeavorhealth.
+
+- **Not all are damaged.** The NYCHH run was a legitimate dedup.
+- **At-risk = clients with the two-catalog + TOGa Commerce setup like Compass.** A per-client
+  assessment (customer-scoped, rehearsed) is **outstanding for a future session**.
+- **Compass Canada was NOT damaged and is structurally immune** — it was not in the merge's
+  client list, has a single catalog, and does not use NetSuite (so no dupe-item bug).
+
+## Change history
+- 2026-09-01 — Recorded the root cause of the Compass MITS outage: the ad-hoc cross-client
+  `duplicate_items_merge_ALL_CLIENTS.sql` (2026-08-31 ~12:43) folded 199 Compass catalog-1
+  store items into their Agilant canonical, producing MITS HTTP 400 (NULL assetType) and SQL
+  1242 (fused duplicate VendorItems). Documented the durable reversal playbook (restore
+  pre-merge snapshot → rebuild damage map → set-based FK-checks-ON re-point of CURRENT
+  customerId=2 lines, NOT a uuid-restore → rehearse on a same-day clone → apply with backup),
+  the customer-scope rule (an unscoped re-point moved 687 Office-Depot lines), the
+  stop-the-sync-first requirement, and the 17-client blast radius with the outstanding
+  per-client assessment. CTO-gated. (jcardinal)
+</content>

package/package.json

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