toga-ai 1.0.1197 → 1.0.1198

package/knowledge/1.0/apps/worker/INDEX.md

@@ -22,7 +22,7 @@
 | [Diagnosing frozen 1.0 worker cron check-ins (Sentry "missed" flood)](workflows/diagnosing-frozen-cron-checkins.md) | Ordered path to diagnose frozen 1.0 worker cron timestamps + a Sentry `worker1` "missed" flood; open when check-ins stall and you suspect a wedged lock. |
 | [isFulfillable Multi-Client Backfill (all togasupply clients)](workflows/isfulfillable-multi-client-backfill.md) | One-time backfill catching up `Items.isFulfillable` on existing items across all 17 togasupply clients; open when running/re-running it or deciding whether rema |
 | [Mapping NetSuite customer address-book entries to Toga Locations (process_netsuite_addressbook_mapping.php)](workflows/netsuite-addressbook-location-mapping.md) | Operator CLI that maps a client customer's NetSuite address-book entry ids to Toga Locations (`Locations_Addresses.c_netsuiteInternalAddressbookId`), so TO impo |
-| [Deduplicating NetSuite duplicate Items across client DBs (recursive MERGE)](workflows/netsuite-duplicate-items-dedup.md) | Per-client cleanup collapsing duplicate `Items` rows (same `partNumber`) to one canonical via recursive MERGE; open before running it — and read the catalog-bli |
+| [Deduplicating NetSuite duplicate Items across client DBs (recursive MERGE)](workflows/netsuite-duplicate-items-dedup.md) | Per-client cleanup collapsing duplicate `Items` rows (same `partNumber`, or same NetSuite id after a rename) to one canonical via recursive MERGE; open before r |
 | [Onboarding a Client to the NetSuite TOGa Supply Sync](workflows/onboarding-client-to-netsuite-togasupply-sync.md) | How to add a new TOGa 2 client to the per-client NetSuite → TOGa Supply importer; open when onboarding a client, and read the vendor-seed / ACL / Parameters-see |
 | [Re-processing NetSuite orders, fulfillments, receipts and inventory adjustments (process_netsuite_*.php)](workflows/reprocessing-one-netsuite-order.md) | Run the real sync for given NetSuite ids on ONE client, without touching cursors: one order (+ its vendor POs), or a list of fulfillments/receipts/inventory adj |
 | [Running a 1.0 worker cron locally without touching prod](workflows/running-a-worker-cron-locally.md) | How to run a real 1.0 worker cron end to end on a Windows laptop with every DB, NetSuite, email and Sentry call kept local; open before running any `worker/cron |

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

@@ -6,12 +6,15 @@ project: Worker
 client: shared
 type: workflow
 status: active
-updated: 2026-10-21
-owners: [jcardinal, rgirish]
+updated: 2026-10-29
+owners: [jcardinal, rgirish, bala]
 files:
   - library/app/api/toga2.php
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
+  - worker1.5/crons/toga2/netsuite/common_sync_togasupply.php
+  - dbchanges2/Client_Elite/2026-10-29a - MergeRenamedSurfaceLaptopItems.sql
 related:
+  - ../../../clients/elite/features/netsuite-togasupply-sync.md
   - ../features/netsuite-togasupply-per-client-sync.md
   - ../../library/features/netsuite-suiteql-rest-shim.md
   - ../../../clients/compass-usa/workflows/catalog-fold-reversal.md
@@ -19,7 +22,7 @@ related:
   - ../../../2.0/apps/dbchanges2/features/netsuite-id-unique-keys.md
 ---
 
-Per-client cleanup collapsing duplicate `Items` rows (same `partNumber`) to one canonical via recursive MERGE; open before running it — and read the catalog-blind warning first, it broke Compass + Quad.
+Per-client cleanup collapsing duplicate `Items` rows (same `partNumber`, or same NetSuite id after a rename) to one canonical via recursive MERGE; open before running it — and read the catalog-blind warning first, it broke Compass + Quad.
 
 ## Summary
 
@@ -48,11 +51,23 @@ One-time, per-client data cleanup that collapses **duplicate `Items` rows sharin
 
 **Deliverables (live in the repo, not the KB):** `test/team/2.0 deployment/duplicate_items_merge_analysis.sql` (read-only per-client duplicate + collision report); the per-client merge migration (the recursive MERGE implementing steps 2–6).
 
+## Merging one renamed item (hand-written `Client_<Name>` file)
+
+A NetSuite item rename makes a second `Items` row with the same `c_netsuiteInternalItemId` (cause in Gotchas). New units, SO / invoice / adjustment lines and vendor items land on the new item; history stays on the old one. Fix = merge new into old, then rename old. Worked example: `dbchanges2/Client_Elite/2026-10-29a - MergeRenamedSurfaceLaptopItems.sql` (TRUE-83395, Elite NetSuite 1390621/1390622, Items 285→63, 284→66).
+
+1. **Count every FK child of the duplicate items and units on prod right before writing the file.** The sync keeps adding rows (Elite `SalesOrderItems` went 8→9 within an hour).
+2. **Check unique keys for clashes before re-pointing:** `Units (itemId, serialNumber)`, `VendorItems (vendorId, itemId, vendorPartNumber)`, `ItemReceiptItemUnits (itemReceiptItemId, unitId)`. A serial received after the rename exists on both items, so merge that unit first (move its `*ItemUnits` rows to the old unit, copy over `locationId` / `c_netsuiteInternalInventoryAssignmentId`, delete the new unit).
+3. **Re-point** `Units`, `SalesOrderItems`, `InvoiceItems`, `InventoryAdjustmentItems`, `TransferOrderItems`, `VendorItems` new→old. Vendor items keep their PO lines and new vendor part numbers.
+4. **Delete the new item, THEN rename the old one.** A rename first fails on `Items` UNIQUE `(catalogId, manufacturerId, partNumber)`, because both rows share catalog + manufacturer.
+5. **Match every statement by `uuid` AND `c_netsuiteInternalItemId`**, never by NetSuite id alone (it is not unique per item, e.g. `X` and `X_` items share one). Rows missing in an env make the statement a no-op, so one file runs on prod and dev-sandbox.
+6. **One transaction.** Every FK to `Items` and `Units` in client DBs is `RESTRICT`, so a missed link fails the delete and rolls back instead of losing data.
+7. **Run with the `mysql` command-line client (stops on error), right after a client sync run ends.** The sync is `*/5` and loads Items/Units at run start; a run in flight fails once on the deleted rows.
+
 ## Gotchas
 
 - **The sync item lookup is Agilant-catalog-only.** Any non-Agilant item is **invisible** to `common_sync_togasupply.php` and will be **re-created** — the whole mechanism behind the duplicates. Deploy the catalog-stamp fix before (and independently of) this cleanup.
-- **`Items` has NO unique constraint on `partNumber`.** Duplicates persist silently; nothing at the DB level prevents them, which is why this is a MERGE-and-clean rather than a rely-on-the-constraint fix.
-- **New duplicates after this cleanup are keyed by NetSuite item id, not part number (2026-10).** The item sync looks up by part number, so a renamed or `_`/`-`-suffixed part number gets a new item for the same `c_netsuiteInternalItemId`. The TRUE-82291 dedupe merges by NetSuite id and a UNIQUE key on it waits for the sync fix — see [NetSuite id UNIQUE keys](../../../2.0/apps/dbchanges2/features/netsuite-id-unique-keys.md).
+- **`Items` UNIQUE key is `(catalogId, manufacturerId, partNumber)`, not `partNumber` alone.** Same part number in another catalog, with another manufacturer, or with NULL catalog passes silently, which is why this is a MERGE-and-clean. The key also blocks renaming an item onto a part number a duplicate still holds.
+- **New duplicates after this cleanup come from NetSuite renames (2026-10).** The 1.0 sync (`getCreateItem` in `toga2.php`, plus the inline item creates in the inventory-adjustment path and the item-fulfillment no-sales-order path) finds an existing item ONLY by normalized `partNumber` (uppercase, trailing `_` stripped) from the Agilant-catalog lookup built at run start in `common_sync_togasupply.php`. `c_netsuiteInternalItemId` is only stamped on create or filled when empty, never used to match. So any rename (or `-` suffix) makes a new item for the same NetSuite id. Units match by `(item, serialNumber)`, so a unit received after the rename duplicates too. Fix one pair by hand: [Merging one renamed item](#merging-one-renamed-item-hand-written-client_name-file). The TRUE-82291 dedupe merges by NetSuite id and a UNIQUE key on it waits for the sync fix — see [NetSuite id UNIQUE keys](../../../2.0/apps/dbchanges2/features/netsuite-id-unique-keys.md).
 - **Client DBs are schema-similar but NOT identical.** Some lack optional tables (e.g. `EntitlementServiceItems`). Run the merge **continue-on-error** so a missing-table MySQL **1146** is a **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).
@@ -60,6 +75,7 @@ One-time, per-client data cleanup that collapses **duplicate `Items` rows sharin
 - **Blast radius of the 2026-08-31 `duplicate_items_merge_ALL_CLIENTS.sql` (assessment complete 2026-09-01):** it ran on 17 clients (Masonite, Ncci, Erau, Shrss, Wmchealth, Trividiahealth, Prudential, Miamidade, Browardsheriff, Nychh, Canon, Quad, Compass, Elite, Growrk, Spglobal, Endeavorhealth). **Only 2 were damaged — Compass and Quad, both two-catalog TOGa Commerce clients.** The other 15 needed no reversal: 13 single-catalog "Agilant"-only clients were a legitimate within-catalog dedup, NYCHH mixed Etilize + NetSuite in one catalog (no fold possible), and Prudential was cleared (single populated catalog; NULL `assetType` is its normal state). Triage per client with `Catalogs` LEFT JOIN `Items` (empty catalogs still show) + the pipeline signal (`c_etilizeProductId` = store vs `c_netsuiteInternalItemId` = Agilant); a client is damaged only if it has a two-catalog store/procurement design AND catalog-1 was folded into catalog-2 AND storefront/transmit depends on catalog-1. See the Compass [catalog-fold reversal](../../../clients/compass-usa/workflows/catalog-fold-reversal.md) and [Quad catalog-fold reversal](../../../clients/quad/workflows/catalog-fold-reversal.md).
 
 ## Change history
+- 2026-10-29 — Rename cause pinned down (part-number-only match, NetSuite id never matched); single renamed-item merge recipe from Elite TRUE-83395; corrected the `Items` unique-key gotcha. (bala)
 - 2026-10-21 — Linked the TRUE-82291 NetSuite-id dedupe + UNIQUE keys; new duplicates come from the part-number lookup. (rgirish)
 - 2026-09-16 — Catalog-blind correction and blast-radius assessment (Compass + Quad damaged). (jcardinal)
 
@@ -67,6 +83,7 @@ One-time, per-client data cleanup that collapses **duplicate `Items` rows sharin
 
 - [NetSuite id UNIQUE keys](../../../2.0/apps/dbchanges2/features/netsuite-id-unique-keys.md)
 - [NetSuite → TOGa Supply Per-Client Sync](../features/netsuite-togasupply-per-client-sync.md)
+- [Elite NetSuite sync](../../../clients/elite/features/netsuite-togasupply-sync.md) (renamed-item merge example)
 - [NetSuite SuiteQL REST shim](../../library/features/netsuite-suiteql-rest-shim.md)
 - [Compass catalog-fold reversal](../../../clients/compass-usa/workflows/catalog-fold-reversal.md)
 - [Compass item catalogs & duplicate items](../../../clients/compass-usa/features/item-catalogs-and-duplicate-items.md)

package/knowledge/clients/elite/features/netsuite-togasupply-sync.md

@@ -6,7 +6,7 @@ project: Worker
 client: elite
 type: client-feature
 status: active
-updated: 2026-10-22
+updated: 2026-10-29
 owners: ["snaredla", "jcardinal", "rgirish", "bala"]
 files:
   - worker/crons/toga2/netsuite/sync_togasupply_elite.php
@@ -23,6 +23,7 @@ files:
   - dbchanges2/Client_Elite/_modules.txt
   - dbchanges2/Client_Elite/2026-09-04a - EliteItemAssetTypeApiWritePermission.sql
   - dbchanges2/_modules/netsuite/2026-09-17a - StaleSalesOrderRetirementAcl.sql
+  - dbchanges2/Client_Elite/2026-10-29a - MergeRenamedSurfaceLaptopItems.sql
   - library/app/api/toga2.php
   - library/app/api/netsuite/rest.php
 related:
@@ -31,6 +32,7 @@ related:
   - ../../../1.0/apps/library/features/netsuite-item-class-sync.md
   - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
   - ../../../1.0/apps/worker/workflows/onboarding-client-to-netsuite-togasupply-sync.md
+  - ../../../1.0/apps/worker/workflows/netsuite-duplicate-items-dedup.md
   - ./salesorder-netsuite-push.md
   - ./supply2-scope.md
   - ../../growrk/features/units-netsuite-custom-fields.md
@@ -421,6 +423,7 @@ Set in `sync_togasupply_elite.php`; they feed the [inventory formula](./inventor
 
 ## Gotchas / known issues
 
+- **A NetSuite item rename makes a duplicate Elite item.** The sync matches items by part number only. 2026-10-26/27: NetSuite 1390621 / 1390622 (Surface Laptop 5, renamed "... - STANDARD" / "... - DEVELOPER") became new Items 285 / 284 beside 63 / 66. Merged back and renamed by `Client_Elite/2026-10-29a` (TRUE-83395). Recipe for the next one: [Merging one renamed item](../../../1.0/apps/worker/workflows/netsuite-duplicate-items-dedup.md#merging-one-renamed-item-hand-written-client_name-file).
 - **Full NS↔toga recheck 2026-10-01: SO/IF/PO/Invoice/IA reconcile.** Expected differences (by design, not bugs):
   - SOs closed in NS (all item lines closed, only Ship/Tax open, no related records) are deleted by the [closed-order rule](../../../1.0/apps/library/features/netsuite-closed-order-rule.md) (10 today).
   - An invoice billed against a $0 hold SO (stored as a TransferOrder) is skipped — e.g. 6215693.
@@ -471,6 +474,7 @@ Set in `sync_togasupply_elite.php`; they feed the [inventory formula](./inventor
   rewinding `NETSUITE_LAST_SYNC_DATETIME_SALES_ORDERS`.
 
 ## Change history
+- 2026-10-29 — Duplicate Items 284/285 from a NetSuite rename merged into 63/66 and renamed (`Client_Elite/2026-10-29a`). TRUE-83395 (bala)
 - 2026-10-22 — Unit serial details sync + new-unit condition "Used" turned on for Elite. TRUE-82991 (bala)
 - 2026-10-01 — Full NS↔toga recheck: list of by-design differences; hand-added users linked to existing Contacts; item descriptions now from NS item record ([doc](../../../1.0/apps/library/features/netsuite-item-description-sync.md)), items 228/80/89/90 backfilled by hand. (rgirish)
 - 2026-09-30 — Elite-only scope flags (owned-warehouse receipts, NS line location, skip TOs from unknown warehouse); NS 196 marked owned; receipt/SO data fixes; 7 closed-order shipments backfilled. (rgirish)

package/package.json

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