toga-ai 1.0.719 → 1.0.721

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/two-catalog-item-model.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
+> [two-catalog item model](../../../clients/compass-usa/features/two-catalog-item-model.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/2.0/apps/api2/features/request-logging.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-29
+updated: 2026-09-01
 owners: ["mhammontree", "dfranks", "bala", "jcardinal"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -16,7 +16,10 @@ files:
 related:
   - ../architecture.md
   - ./api-payload-interceptors.md
+  - ./v2-api-error-codes.md
+  - ../../_underscore/features/error-reporting-issue-event.md
   - ../../../../clients/aig/features/entitlement-intake.md
+  - ../../../../clients/compass-usa/features/mits-po-to-so-item-linking.md
   - ../../../../clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md
 ---
 
@@ -146,6 +149,67 @@ transaction no matter how many times apiproxy retried. That is why the retry att
 there even in principle — the two logs are not two views of the same rows. Join the two by
 `transactionId` when you need the full attempt sequence for one user action.
 
+## Getting the REAL error behind a generic `EO-1` 500 (the three-hop chain)
+
+A 500 whose only content is `EO-1` — *"Operation Failed: An internal server error occurred"* —
+names neither the failing field nor the value. Very often the true failure is a **validation error
+on a NESTED sub-request** that `internalApiRequest()` issued inside the outer write, and it is fully
+recorded — just in three different places. Walk them in order.
+
+**1. Decode `error.id` → `Logs.Issue` + `Logs.Event`.** The envelope carries `error.id` shaped
+`<Issue.reference>-<Event.eventNumber>` (e.g. `QT-605`). Query the **prod `Logs`** schema:
+
+```sql
+# reference is the part BEFORE the dash — searching for the whole 'QT-605' matches NOTHING
+SELECT id, reference, status, errorMessage, trace, totalOccurrences, dtLastOccurred
+FROM Issue
+WHERE reference = 'QT';
+
+SELECT clientId, dtCreated, errorMessage
+FROM Event
+WHERE issueId = <issue.id> AND eventNumber = 605;
+```
+
+Full semantics of the reference encoding live in
+[Error Reporting — Issue/Event Capture](../../_underscore/features/error-reporting-issue-event.md).
+
+**2. Read `Issue.trace`, not `Issue.errorMessage`.** `Issue.errorMessage` and `Event.errorMessage`
+are **`varchar(255)`** and truncate, and on an api2 validation failure the cut lands **exactly where
+the useful part begins** — the `identifiers` / `searchCriteria` block naming the field and the value
+that matched nothing. `Issue.trace` is full text and gives the exact `file:line` chain, which is
+usually enough to identify *which* nested call failed even though it never tells you *with what
+value*.
+
+**3. The complete inner error is a row in `Logs_<Client>.Api` — and you CANNOT find it by the outer
+`transactionId`.** `internalApiRequest()` logs **every nested sub-request** as its own client-log
+row, and since the 2026-08-25 collision fix that row's `transactionId` is a **freshly generated
+random uuid** (`_String::generateUuid()`), deliberately unrelated to the outer request — see
+[api2 architecture](../architecture.md). So the inner row shares **nothing** with the caller except
+its timestamp. Locate it by **`dtStamp` window + `route`**, then read its `responsePayload`, which
+carries the complete message including `identifiers` and `searchCriteria`.
+
+```sql
+SELECT id, dtStamp, route, method, responseCode, LEFT(responsePayload, 2000)
+FROM Logs_Compass.Api
+WHERE
+    dtStamp BETWEEN '2026-09-01 04:12:00' AND '2026-09-01 04:12:30' AND
+    route LIKE '/v2/purchase-orders%'
+ORDER BY dtStamp;
+```
+
+> **⚠ Three traps in this chain**, each of which has already sent an investigation the wrong way:
+> searching `Issue.reference` for the **full** `QT-605` string (it stores only `QT`); believing the
+> **truncated** `errorMessage` is the whole error (it is severed at 255 chars, right before the
+> field name); and trying to join the inner sub-request row by `transactionId` (it is random by
+> design, so the join returns nothing and reads as "the inner call was never logged").
+
+**Worked example.** A Compass `POST /v2/purchase-orders` returned `EO-1`/`QT-605`. `Issue.trace`
+pointed at `internalApiRequest()` (`V2.php` ≈L2433); the matching `Logs_Compass.Api` row for the
+nested sales-order write held the real verdict — **`EV-12` "unable to find a unique match" on field
+`item`** for a part number scoped to the wrong catalog. Nothing in the 500 the caller saw contained
+the word `item`. See
+[Compass MITS PO → SO item linking](../../../../clients/compass-usa/features/mits-po-to-so-item-linking.md).
+
 ## Blind spots when auditing a client's API traffic
 
 Looking only at `Logs_<Client>.Api` misses four sources:
@@ -225,6 +289,16 @@ re-send.
 
 ## Change history
 
+- 2026-09-01 — Added **Getting the REAL error behind a generic `EO-1` 500** — the three-hop chain
+  from an opaque 500 to the actual failing field. Key new fact: `internalApiRequest()` logs each
+  **nested** sub-request into `Logs_<Client>.Api` under a **randomly generated `transactionId`**
+  (the 2026-08-25 collision fix), so the inner row **cannot** be joined to the outer request — find
+  it by `dtStamp` window + `route` and read its `responsePayload`, which is the only place the
+  `identifiers`/`searchCriteria` survive. Also recorded that `error.id` is
+  `<Issue.reference>-<Event.eventNumber>` and `Issue.reference` stores only the part **before** the
+  dash, and that the `varchar(255)` `errorMessage` truncates exactly where the field name starts, so
+  `Issue.trace` is what to read. Found while root-causing the Compass MR purchase-order 500 storm
+  (`EV-12` on `item`, hidden behind `EO-1`). No code change. (bala)
 - 2026-08-29 — Noted that `Logs.Api.route` values are stored **with the `/v2` prefix** (e.g.
   `/v2/inventory-adjustments/{uuid}`), so narrowing queries must filter `route LIKE '/v2/...'` — a
   bare `/inventory-adjustments` predicate matches nothing. Reinforced that a narrowed row's

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,9 +6,9 @@
 | [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, 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 |
 | [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, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |
+| [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 |
 | [Compass MITS PO rejection — zero line items (400 + Issue + PM alert email)](features/mits-po-zero-line-item-rejection.md) | 2.0 | MITS transmits Compass purchase orders that carry **`"purchaseOrderItems": []`** (real example: PO `50309196-1`, `mitsSalesOrder` `MR244630`). | _underscore/Model/Compass/PurchaseOrder.php, _underscore/Model/Compass/Usa/PurchaseOrder.php, _underscore/Model/Compass/Canada/PurchaseOrder.php, worker2/Worker/Client/Compass/reports/PurchaseOrderRejectionEmail.php |
 | [Compass MITS Sales-Order Transmit Alerting (US Issue/Event vs Canada in-cron email)](features/mits-sales-order-transmission-alerting.md) | 2.0 | How a failure in the `1_transmit_..._sales_orders_to_mits.php` cron reaches a human — for **both** Compass tenants, because **they no longer work the same way** | worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, worker/crons/toga2/compasscanada/workflow/1_transmit_compassCanada_sales_orders_to_mits.php, worker2/Worker/Infrastructure/Errors.php, tools/mvc/errors/post.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/IssueEmailAddress.php, dbchanges2/Logs/2026-08-04a - MITS rejection business recipients.sql |
@@ -21,7 +21,9 @@
 | [Persona Model & Levy-Sector Gating (worker2 PEOPLE cron)](features/persona-model-and-levy-gating.md) | 2.0 | Compass USA catalogue visibility is driven by **personas** in `Client_Compass`. | worker2/Worker/Client/Compass/PeopleFile.php |
 | [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 — intentional two-catalog Item model (store vs Agilant procurement)](features/two-catalog-item-model.md) | 2.0 | Compass USA keeps its items in **two intentional catalogs**, and the **same part number legitimately exists once per catalog**. | library/app/api/toga2.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.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

@@ -10,10 +10,13 @@ updated: 2026-09-01
 owners: ["bala"]
 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
 related:
   - odp-edi-850-item-resolution.md
+  - mits-po-to-so-item-linking.md
   - isfulfillable-data-quality-and-type-rule.md
   - ../workflows/odp-duplicate-po-line-cleanup.md
   - ../workflows/odp-order-pipeline-to-netsuite.md
@@ -30,7 +33,9 @@ two halves are routinely mistaken for one. **This is the first thing to check wh
 item "exists but is not found."** A part number that is present, active and correct in
 `Client_Compass.Items` will still fail a lookup that is scoped to the wrong catalog — which is
 exactly how the 2026-08-31 Office Depot EDI import outage happened
-([ODP EDI 850 line-item resolution](odp-edi-850-item-resolution.md)).
+([ODP EDI 850 line-item resolution](odp-edi-850-item-resolution.md)) and, the same night, how every
+Compass **MITS MR purchase order** for an Agilant-catalog SKU started returning an opaque HTTP 500
+([MITS PO → SO item linking](mits-po-to-so-item-linking.md)).
 
 The second half of the same problem: the NetSuite sync **creates a second `Items` row** for a
 product that already exists in the other catalog rather than matching it, so one physical product
@@ -85,14 +90,16 @@ in catalog 1 under a slightly different part number gets a **second `Items` row*
 
 Plus `-1` / `-2` suffixed copies: items **2431, 2432, 2443, 2653**.
 
-**Two distinct duplicate shapes exist and they fail differently:**
+**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.
-- **Same part number, two catalogs** — this is the
+  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
-  duplicate lines across 1,320 Office Depot POs), and it is also why a part-number lookup that
-  **drops** the catalog filter can silently pick the wrong sibling: verified on a local
-  `Client_Compass` snapshot, **243** part numbers exist in more than one catalog.
+  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)).
 
 ## "Who changed this part number?" — the audit trail says nobody
 
@@ -115,7 +122,18 @@ children" rule:
 
 - **⚠ Never scope a Compass item lookup to one catalog** unless you have proved the item can only
   come from that source. The correct default is `Items.partNumber IN (...)` with **no** catalog
-  condition, and then reference the resolved record **by `uuid`**.
+  condition, and then reference the resolved record **by `uuid`**. **The catalog filter never buys
+  uniqueness on Compass** — `Items.partNumber` is unique across the whole table (re-verified prod
+  2026-09-01) — so every catalog condition is pure downside.
+- **⚠ The 2.0 side hardcodes the OTHER catalog, and it broke MR purchase orders.**
+  `_Model_Compass_PurchaseOrder::handleMrOrder` builds each SO item as
+  `['partNumber' => …, 'catalog' => ['uuid' => static::COMPASS_CATALOG_UUID]]`, and
+  `_Model_Compass_Usa_PurchaseOrder::COMPASS_CATALOG_UUID` is `961dbcbc…` = **catalog 1
+  (Compass)**. So the 1.0 sync can only ever *write* catalog 2 and the 2.0 MR handler can only ever
+  *read* catalog 1 — the two hardcodes point in opposite directions. Any MR order for a catalog-2
+  SKU (`C40QYUC`, `B97TGUC`, `4U555A-S`, …) resolves zero rows → api2 `EV-12` → opaque `EO-1` 500
+  with MITS retrying forever. Details, blast radius and fix:
+  [MITS PO → SO item linking](mits-po-to-so-item-linking.md).
 - **⚠ 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.
@@ -127,6 +145,14 @@ children" rule:
   ([850 line-item resolution](odp-edi-850-item-resolution.md)).
 
 ## Change history
+- 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
+  1.0 sync's hardcoded `'Agilant'` (catalog **2**) — one only writes catalog 2, the other only reads
+  catalog 1. MR POs for `C40QYUC` / `B97TGUC` / `4U555A-S` therefore failed api2 `EV-12` and surfaced
+  as an opaque `EO-1` 500 (`Logs.Issue` reference `QT`, 660 occurrences, 10 POs blocked overnight
+  2026-08-31). Also promoted "the catalog filter never buys uniqueness" into the gotchas, since
+  `Items.partNumber` uniqueness across the whole table was re-verified on prod the same day. (bala)
 - 2026-09-01 — Documented the `Client_Compass` catalog split as its own subject after it caused the
   2026-08-31 ODP EDI import outage: catalogs 1 "Compass" (Etilize, `c_etilizeProductId`) / 2
   "Agilant" (1.0 NetSuite sync, `c_netsuiteInternalItemId`) / 3 with their uuids and prod counts
@@ -135,8 +161,10 @@ children" rule:
   `syncItemFulfillmentFromNetsuite()`, `syncInventoryAdjustmentFromNetsuite()` and the
   Agilant-only lookup built in `common_sync_togasupply.php` — which is **why** the sync creates a
   duplicate instead of matching. Listed the observed duplicate pairs (1815/2839, 2216/2427,
-  2225/2430, plus 2431/2432/2443/2653) and separated the two duplicate shapes (different part
-  numbers vs. same part number in two catalogs, 243 such part numbers on a local snapshot).
+  2225/2430, plus 2431/2432/2443/2653) and separated the two duplicate shapes: **different** part
+  numbers is the live shape, while **same** part number in two catalogs is **not present in prod**
+  (verified on prod 2026-09-01 — zero duplicated part numbers, zero spanning two catalogs), so it
+  is a latent risk only.
   Recorded the audit-trail method (`Logs_Compass.Record` ⋈ `RecordField`, `recordId` 21 = Items,
   `recordFieldId` 108 = partNumber) and its verdict: every `partNumber` row is a create with a NULL
   `oldValue` by `apiId = 1`, so **nobody renamed anything**. Data/investigation finding, no code

package/knowledge/clients/compass-usa/features/mits-po-to-so-item-linking.md

@@ -6,15 +6,20 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-08-13
+updated: 2026-09-01
 owners: ["jcardinal", "rgirish", "dfranks", "bala"]
 files:
   - _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
 related:
   - asn-to-item-fulfillment.md
   - mits-po-transmission-to-vendors.md
   - mits-po-zero-line-item-rejection.md
+  - item-catalogs-and-duplicate-items.md
+  - ../../../2.0/apps/api2/features/request-logging.md
+  - ../../../2.0/apps/api2/features/v2-api-error-codes.md
 ---
 
 ## Summary
@@ -109,7 +114,9 @@ per-api renames and interceptor scoping interact.
   returns early. `handleMrOrder` creates/appends the SO from the PO items, **strips**
   `createdFromSalesOrderItem`, and deliberately **aligns** SO and PO `lineNumber`s. It does
   NOT build the item bridge — so the `postPost` lineNumber-match pass is the **only** (and
-  correct) MR linking mechanism.
+  correct) MR linking mechanism. Each SO item it builds references the item as
+  `partNumber` **plus a hardcoded catalog uuid**, which is the cause of the MR 500 outage below —
+  see [MR POs 500 when the item is outside the Compass catalog](#-mr-pos-500-when-the-item-lives-outside-the-compass-catalog-open-as-of-2026-09-01).
 - **MA orders — item population in the ODP PO import cron:** the 3a cron
   (`worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php`) parses ODP
   EDI 850 POs. Its "Non-SA order handling" block creates the Compass **MA** sales order. Line
@@ -140,6 +147,57 @@ per-api renames and interceptor scoping interact.
 USA and Canada share the parent handler unchanged.
 
 ## Gotchas / known issues
+### ⚠ MR POs 500 when the item lives outside the Compass catalog (OPEN as of 2026-09-01)
+
+**Symptom.** `POST /v2/purchase-orders` on `api-writer.togahub.com` returns **HTTP 500** with the
+generic envelope error **`EO-1`** ("Operation Failed: An internal server error occurred"). MITS has
+no backoff, so it **retries every few seconds forever** — 66 attempts were observed for a single PO.
+Sibling POs on the *same* MR sales order succeed, which makes it look intermittent. It is not: it is
+**per part number**.
+
+**Cause.** `_Model_Compass_PurchaseOrder::handleMrOrder` (≈L61) builds every `salesOrderItems`
+item reference **scoped to one catalog**:
+
+```php
+'item' => [
+    'partNumber' => $partNumber,
+    'catalog'    => ['uuid' => static::COMPASS_CATALOG_UUID],
+]
+```
+
+`COMPASS_CATALOG_UUID` on `_Model_Compass_Usa_PurchaseOrder` is
+`961dbcbc-1943-11ef-8e3b-0aae2980db55` = **`Client_Compass.Catalogs` id 1 ("Compass")**. But
+`Client_Compass` has **three** catalogs (1 Compass, 2 Agilant, 3 Office Depot) and a large set of
+MITS part numbers are `Items` rows under **catalog 2 (Agilant)** — observed: `C40QYUC`, `C40QYUC-1`,
+`B97TGUC`, `B97TGUC-1`, `4U555A-S`. The catalog-scoped reference resolves **zero** rows, api2 raises
+**`EV-12`** ("unable to find a unique match … requires an exact match for locating the child
+record") on field `item`, `internalApiRequest` (`api2/Component/Api/V2/V2.php` ≈L2433) throws, and
+the **whole outer purchase-order request rolls back as a 500**. The precise field and value never
+reach the caller — only `EO-1` — which is why this reads as an unexplained platform fault.
+
+**The catalog filter buys nothing.** `Client_Compass.Items.partNumber` is **unique across the entire
+table** (verified on prod 2026-09-01 — zero duplicated part numbers, zero spanning two catalogs), so
+scoping the lookup to one catalog adds **no** uniqueness and only manufactures false misses. This is
+the same trap that caused the 2026-08-31 ODP EDI import outage — see
+[Compass Item Catalogs](item-catalogs-and-duplicate-items.md).
+
+**Fix (not yet applied).** Either drop the `catalog` key so the lookup is by `partNumber` alone, or
+resolve the item **uuid** first with an internal `GET /items` and pass `['uuid' => …]`, throwing a
+clear `_Exception_Business` when the part number matches nothing. The second shape is preferable: it
+turns an opaque 500-and-retry-forever into a named business rejection.
+
+**Blast radius observed (2026-08-31 23:00 → 2026-09-01).** `Logs.Issue` reference **`QT`**
+(issue id 602) accumulated **660** occurrences. **Ten** Compass MITS POs were blocked — `50312113-1`,
+`50312116-1`, `50312117-1`, `50312119-1`, `50312122-1`, `50312144-1`, `50312161-1`, `50312176-1`,
+`50312180-1`, `50312182-1` (MR245464/65/66/69/70/72/73/76/79/80). All ten were re-submitted
+successfully on 2026-09-01 between 11:24 and 11:43 once the items existed where the lookup looked.
+Sibling POs on the same MR sales orders (`50312114-1`, `50312120-1`, …) went through fine because
+their item `9X3V1UT` sits in catalog 1.
+
+**Recurrence risk is high, not theoretical.** Any Compass MR order for an Agilant-catalog SKU hits
+it — custom Azure-tenant SKUs and kitting SKUs land in catalog 2 by construction, because the 1.0
+NetSuite sync can only create there.
+
 - **SQL injection in `prePost` (OPEN as of 2026-08-03).** `_underscore/Model/Compass/PurchaseOrder.php`
   **L232** interpolates the raw client payload straight into SQL:
   `WHERE SalesOrders.number LIKE '{$payload->mitsSalesOrder}'` — no escape, no cast. The **same
@@ -227,6 +285,16 @@ USA and Canada share the parent handler unchanged.
   need item backfill from the sibling ODP SO first).
 
 ## Change history
+- 2026-09-01 — **Root-caused the MR PO `EO-1` 500 storm** (2026-08-31 23:00 → 2026-09-01,
+  `Logs.Issue` reference `QT`, issue id 602, 660 occurrences, 10 POs blocked, MITS retrying every few
+  seconds with no backoff). `handleMrOrder` (≈L61) references each SO item as `partNumber` **plus**
+  `static::COMPASS_CATALOG_UUID` (`961dbcbc…` = `Client_Compass.Catalogs` id 1 "Compass"), but
+  several MITS part numbers (`C40QYUC`, `C40QYUC-1`, `B97TGUC`, `B97TGUC-1`, `4U555A-S`) are catalog-2
+  **Agilant** items, so the scoped lookup matches nothing → api2 `EV-12` on field `item` →
+  `internalApiRequest` throws → the outer PO write rolls back as an opaque 500. The catalog filter
+  adds no uniqueness (`Items.partNumber` is unique across the whole table, verified on prod), so the
+  fix is to drop the `catalog` key or resolve the item uuid first and fail with a business
+  exception. **No code change yet — the ten POs were re-submitted manually.** (bala)
 - 2026-08-13 — The zero-line-item rejection this doc's caller analysis was written to scope **has
   shipped** as the first statement of `prePost` (TRUE-80412), so `handleMrOrder` can no longer create
   a zero-item Sales Order for an MR PO. It is MITS-only by construction (`apiId = 2` interceptor rows

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
+  - two-catalog-item-model.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
+[two-catalog item model](./two-catalog-item-model.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/features/odp-edi-850-item-resolution.md

@@ -119,17 +119,19 @@ different one than the EDI importer posts against. Full catalog model, counts, a
 duplicate-item problem behind it:
 [Compass item catalogs & duplicate items](item-catalogs-and-duplicate-items.md).
 
-### ⚠ Dropping the catalog filter widened the ambiguity the resolver can see
-Two consequences the code does **not** handle:
-
-- **The exact-match branch has no ambiguity check.** `fetchPartNumbersCompassCarries()` builds
-  `$lookup[strtoupper($partNumber)] = ['partNumber' => …, 'uuid' => …]` — one entry per part
-  number — so when the **same part number exists in more than one catalog**, the **last row api2
-  returns wins** and its uuid is used, silently. (Verified on a local `Client_Compass` snapshot:
-  **243** part numbers exist in more than one catalog; the exact prod count differs, the shape does
-  not. This is the same dual-catalog SKU shape as the
-  [duplicate PO-line bug](../workflows/odp-duplicate-po-line-cleanup.md).) If an ODP line ever
-  resolves to the wrong sibling item, this is the place to look.
+### Two things the resolver does not check now that the catalog filter is out
+Neither is a live problem — the first is latent, the second is safe by design:
+
+- **The exact-match branch has no ambiguity check — latent, cannot fire today.**
+  `fetchPartNumbersCompassCarries()` keys its lookup **one entry per uppercased part number**
+  (`$lookup[strtoupper($partNumber)] = ['partNumber' => …, 'uuid' => …]`), so **if** the same part
+  number were ever created in two catalogs, this branch would silently take whichever row api2
+  returned **last** and use its uuid — unlike the vendor-SKU branch below, which counts candidates
+  and rejects an ambiguous match.
+  **Verified on prod `Client_Compass` 2026-09-01: zero part numbers are duplicated at all, and zero
+  span more than one catalog**, so the branch cannot pick a wrong sibling today. Re-check this if
+  duplicate part numbers ever reappear — the shape that would produce them is the
+  [dual-catalog duplicate PO-line bug](../workflows/odp-duplicate-po-line-cleanup.md).
 - **Only the vendor-SKU branch counts candidates.** `count($vendorSkuMatches) == 1` still gates
   step 2, so an ambiguous SKU is **reported, never guessed** — picking one silently would ship the
   wrong item. Recorded ambiguous SKUs: `7128204` (`AW5M5UT` / `AW5M5UT-1`), `7423324`
@@ -269,8 +271,9 @@ internal ids **7437998, 7437898, 7438098**).
   `partNumber` + `catalog` 400s **`EV-12`** when that pair is not unique (send the `uuid`
   instead); a `where` with a **single** condition still needs the `'and' =>` wrapper or api2
   returns **500 `EO-1`** with an empty `transactionId` (this cost a deploy cycle); and dropping the
-  catalog filter means the **exact-match branch now silently takes the last row** when one part
-  number exists in two catalogs, because that branch counts no candidates. Corrected the
+  catalog filter leaves the **exact-match branch without an ambiguity check** — latent only, since
+  prod has **zero** duplicated part numbers and **zero** spanning two catalogs (verified on prod
+  2026-09-01), unlike the vendor-SKU branch which counts candidates. Corrected the
   "nothing is written" claim — the failing runs left zero-item ODP SOs `481137047001` /
   `481143381001` despite the email saying nothing was created. Verified end to end on prod (all
   three POs imported and reached NetSuite). (bala)

package/knowledge/clients/compass-usa/features/two-catalog-item-model.md

@@ -0,0 +1,103 @@
+---
+title: Compass USA — intentional two-catalog Item model (store vs Agilant procurement)
+framework: "2.0"
+project: _Underscore
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-09-01
+owners: ["jcardinal"]
+files:
+  - library/app/api/toga2.php
+  - worker/crons/toga2/netsuite/common_sync_togasupply.php
+  - worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php
+related:
+  - ../workflows/catalog-fold-reversal.md
+  - ./mits-sales-order-transmission-alerting.md
+  - ../../../1.0/apps/worker/workflows/netsuite-duplicate-items-dedup.md
+  - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
+---
+
+## Summary
+
+Compass USA keeps its items in **two intentional catalogs**, and the **same part number
+legitimately exists once per catalog**. These are **not duplicates** — folding them together
+broke MITS transmission platform-wide (see
+[catalog-fold reversal](../workflows/catalog-fold-reversal.md)). `Client_Compass.Catalogs`:
+
+| id | name | Purpose |
+|---|---|---|
+| 1 | **Compass** | Customer / store catalog. Items carry store classification (`assetType`, `category`, `type`). |
+| 2 | **Agilant** | Procurement / NetSuite catalog. Items are synced from NetSuite; **no** classification fields. |
+| 3 | Office Depot | Empty. |
+
+**Rule: a part number that appears in both catalogs is one item per catalog, on purpose.**
+Any dedup/merge that treats cross-catalog same-part-number rows as duplicates is wrong for
+this client.
+
+## Customer → catalog rule (which catalog an order resolves to)
+
+Confirmed by the developer and by pre-merge data:
+
+- **`customerId = 2` (Compass) sales orders → catalog 1 (store) items.**
+- Everyone else — **Office Depot `customerId = 1`, Agilant `customerId = 3`** → catalog 2
+  (Agilant) items.
+
+Verified pre-merge (2026-08-31 snapshot): `customerId = 2` order lines were ~100% on
+catalog 1 (**182,787 vs 1**).
+
+**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. Scope by `customerId = 2`.
+
+## Why the store catalog matters for MITS
+
+The MITS transmit cron needs the **store** classification. When a Compass order line resolves
+to an **Agilant** (catalog-2) item, that item has `assetType`/`category`/`type` NULL, so the
+payload `assetType` is null and **MITS rejects the whole order** (HTTP 400 "The AssetType
+field is required"). So the customer→catalog mapping is load-bearing, not cosmetic. See
+[MITS sales-order transmit alerting](./mits-sales-order-transmission-alerting.md).
+
+## How NetSuite → TOGa Supply sync interacts with the catalogs
+
+The NetSuite → TOGa Supply sync is **Agilant-catalog-only**. This has two durable
+consequences for Compass:
+
+- **Item CREATE always stamps `catalog: Agilant` and sets NO classification.**
+  `App_Api_Toga2::getCreateItem` (`library/app/api/toga2.php` ~L6194-6270) builds the create
+  payload with `catalog => Agilant` and no `assetType`/`category`/`type`; the item lookup in
+  `worker/crons/toga2/netsuite/common_sync_togasupply.php` is built off the Agilant catalog
+  only. So **new items are born on catalog 2, unclassified** — and a Compass order line landing
+  on such an item fails MITS.
+- **Item UPDATE only PUTs `inventoryType` / `isFulfillable`, never `assetType`/`category`/
+  `type`.** So once classification is set on an item it is **durable across sync runs** — the
+  sync will not revert it. The problem is only **new** items, which arrive unclassified.
+
+**Consequence for any data repair:** because the sync re-creates Compass order lines pointing
+at Agilant items, a store-catalog reversal is only durable if the **Compass NetSuite sync is
+stopped first**. Re-enabling it risks re-pointing new/re-synced Compass orders back to Agilant
+(2 such lines were observed right after a test re-enable). A proper long-term fix is a
+sync-lookup change so `customerId = 2` resolves to catalog 1 — outstanding.
+
+## Gotchas / known issues
+
+- **Same part number in both catalogs is NOT a duplicate.** The cross-client
+  [duplicate-items dedup](../../../1.0/apps/worker/workflows/netsuite-duplicate-items-dedup.md)
+  treated Compass's catalog-1 twins as dupes and folded 199 of them into Agilant, causing the
+  MITS outage. Any dedup on this client must be **catalog-aware**.
+- **The MITS crons hold API credentials inline** in the transmit files — treat them as
+  secret-bearing when copying snippets anywhere.
+- Catalog 3 (Office Depot) is empty — do not assume Office Depot orders use it; ODP customer
+  `customerId = 1` resolves to catalog 2.
+
+## Change history
+- 2026-09-01 — Documented Compass USA's intentional two-catalog item model (1 = Compass/store
+  with classification, 2 = Agilant/NetSuite procurement without), the `customerId = 2` →
+  catalog 1 rule (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). Recorded that the NetSuite →
+  TOGa Supply sync is Agilant-catalog-only: CREATE stamps `catalog: Agilant` with no
+  classification (new items born unclassified → MITS 400), while UPDATE never touches
+  classification (so a set value is durable). Written after the cross-client dedup folded 199
+  catalog-1 twins into Agilant and broke MITS. (jcardinal)
+</content>
+</invoke>

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

@@ -31,6 +31,8 @@ related:
   - workflows/granting-persona-bundle-access.md
   - workflows/granting-navigation-access.md
   - features/mits-sales-order-transmission-alerting.md
+  - features/two-catalog-item-model.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/two-catalog-item-model.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/two-catalog-item-model.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/two-catalog-item-model.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.719",
+  "version": "1.0.721",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",