toga-ai 1.0.720 → 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/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

@@ -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/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/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.720",
+  "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",