toga-ai 1.0.415 → 1.0.417

package/knowledge/1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-07-09
-owners: ["dfranks", "bala"]
+owners: ["dfranks", "bala", "jcardinal"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
   - worker/crons/toga2/netsuite/sync_togasupply_canon.php
@@ -196,8 +196,26 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
   excluded** from the NetSuite Sync Alert monitor — including it would generate permanent
   false-positive stale tickets.
 
+- **`syncSalesOrderFromNetsuite` reconciled existing customer-PO lines by `uuid` ONLY → duplicate
+  PO lines on dual-catalog SKUs.** When a physical SKU exists as **two `Items` records across
+  catalogs** (same `partNumber`, different `uuid` — e.g. a customer-catalog `HYBRID` item vs. an
+  internal `SERIALIZED` item), the fulfillment SO item can resolve to the *other-catalog* `Item`
+  than the line already on the PO. The uuid-only match (and uuid-only retrieval) misses the sibling
+  line, so the importer **appends a duplicate PO line** backed by an auto-created **"shadow"
+  VendorItem** (`vendorPartNumber` = SKU literal, description NULL, cost 0). Observed on Compass
+  (`vendorId=1` Office Depot): 4,886 duplicate lines across 1,320 POs. **Fix (2026-07-22):** added
+  a `partNumber` (SKU) fallback retrieval + lookup, and gated VendorItem creation to fire only when
+  a new line is actually created. Full root cause, the prod cleanup migration, and the
+  deploy-fix-before-cleanup sequencing live in the
+  [Compass ODP Duplicate PO-Line Cleanup](../../../clients/compass-usa/workflows/odp-duplicate-po-line-cleanup.md).
+
 ## Change history
 
+- 2026-07-22 — Recorded the **dual-catalog duplicate OD PO-line bug** in
+  `syncSalesOrderFromNetsuite` (uuid-only PO-line reconciliation → shadow-VendorItem duplicate
+  lines) and its SKU-fallback fix. Compass cleanup + sequencing captured in the
+  [Compass ODP Duplicate PO-Line Cleanup](../../../clients/compass-usa/workflows/odp-duplicate-po-line-cleanup.md).
+  Code + migration uncommitted, pending deploy. (jcardinal)
 - 2026-07-20 — Fixed a pre-existing **missing `try`-close / brace bug** in
   `common_sync_togasupply.php` (the inventory-adjustments and item-fulfillments blocks lacked a
   `try` close, a parse error that broke the Compass sync run). Same failure class as the 2026-07-09

package/knowledge/INDEX.md

@@ -4,7 +4,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 13 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 14 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 15 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
 - **togadesk** (TOGa Desk) — 9 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)

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

@@ -11,5 +11,6 @@
 | [Compass MR/MA Order Auto-Approval & Status Gate](features/mr-ma-order-approval-and-status.md) | 2.0 | Compass **MR** and **MA** sales orders are system-generated from the MITS / Office Depot EDI pipeline (they do not originate as user-entered SA orders) and must | _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/PurchaseOrder.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |
 | [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 |
+| [Compass Office Depot Duplicate PO-Line Cleanup (dual-catalog SKU)](workflows/odp-duplicate-po-line-cleanup.md) | 1.0 | The NetSuite fulfillment-sales-order importer duplicated Office Depot purchase-order lines on Compass USA because it reconciled the fulfillment SO against the e | library/app/api/toga2.php, dbchanges2/Client_Compass/2026-07-22a - CleanupOfficeDepotDuplicatePurchaseOrderItems.sql |
 | [Compass ODP Order Pipeline to NetSuite (numbered worker crons)](workflows/odp-order-pipeline-to-netsuite.md) | 1.0 | The end-to-end **Compass Office Depot (ODP) order → NetSuite** pipeline as it actually runs through the 1.0 `worker` crons under `worker/crons/toga2/compass/`, | worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, worker/crons/toga2/compass/edi/1_download_edi_s3_create_po_toga.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, library/app/client/compass.php |
 | [Compass Order Lifecycle & Data-Integrity Invariants](workflows/order-lifecycle-and-data-integrity.md) | 2.0 | End-to-end map of how a Compass order flows through the `Client_Compass` (2.0) database and the **expected raw-data shape** at each link/ASN/IF level. |  |

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

@@ -24,6 +24,7 @@ related:
   - features/cost-centers.md
   - features/approval-decision-flow.md
   - workflows/cross-kit-bundle-corruption.md
+  - workflows/odp-duplicate-po-line-cleanup.md
   - ../../2.0/apps/worker2/features/compass-vip-support-importer.md
   - ../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
   - ../../2.0/apps/toga2-commerce/features/cart-bundle-submission-and-identity.md
@@ -65,6 +66,11 @@ separate, related client (see its own profile).
 - **Office Depot (ODP)** — vendor id 1. ASNs arrive via **cXML** (direct V2 API) and via the
   email cron's ODP CSV format.
 - **Strategic Systems** — ASNs via the email cron's SS CSV format (serial numbers → Units).
+- **Dual-catalog SKU → duplicate OD PO lines (2026-07-22).** A physical SKU that exists as two
+  `Items` rows (same `partNumber`, different `uuid`) made `syncSalesOrderFromNetsuite` append
+  duplicate Office Depot PO lines backed by shadow VendorItems (4,886 dup lines / 1,320 POs).
+  Root cause, forward fix, and the `2026-07-22a` cleanup migration:
+  [ODP Duplicate PO-Line Cleanup](workflows/odp-duplicate-po-line-cleanup.md).
 - ASN ingestion entry points: cXML to the V2 API (logged in `Logs_Compass.Api`) and
   `worker/crons/toga2/compass/workflow/3b_import_strategic_systems_advance_shipping_notices.php`.
 

package/knowledge/clients/compass-usa/workflows/odp-duplicate-po-line-cleanup.md

@@ -0,0 +1,103 @@
+---
+title: Compass Office Depot Duplicate PO-Line Cleanup (dual-catalog SKU)
+framework: "1.0"
+repo: library
+project: Library
+client: compass-usa
+type: workflow
+status: active
+updated: 2026-07-22
+owners: ["jcardinal"]
+files:
+  - library/app/api/toga2.php
+  - dbchanges2/Client_Compass/2026-07-22a - CleanupOfficeDepotDuplicatePurchaseOrderItems.sql
+related:
+  - clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md
+  - clients/compass-usa/workflows/odp-order-pipeline-to-netsuite.md
+  - clients/compass-usa/features/mits-po-to-so-item-linking.md
+  - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
+  - clients/compass-usa/profile.md
+---
+
+## Summary
+
+The NetSuite fulfillment-sales-order importer duplicated Office Depot purchase-order lines on
+Compass USA because it reconciled the fulfillment SO against the existing customer PO by matching
+existing PO lines **only on `VendorItems.item.uuid`**. When one physical SKU exists as **two
+`Items` records across catalogs** (same `partNumber`, different `uuid` — e.g. a customer-catalog
+`HYBRID` item vs. an internal `SERIALIZED` item), the fulfillment item can resolve to the
+*other-catalog* `Item` than the line already on the PO. The uuid match then misses (the uuid-only
+retrieval never even loaded the sibling line), and a **duplicate PO line** is appended, backed by
+an auto-created **"shadow" VendorItem** (`vendorPartNumber` = SKU literal, `vendorPartDescription`
+NULL, `overridePoSubmissionIntegrationId` NULL, cost 0).
+
+**Blast radius (prod `Client_Compass`):** 4,886 duplicate lines across 1,320 Office Depot POs.
+Reference order: SO **SA133668** → OD PO **41342788-5125** (PO id 104382), duplicate lines
+179909 / 179910 / 179911.
+
+This doc is both the durable **integration gotcha** (the reconciliation behavior) and the
+**data-repair record + reusable pattern** for the one-time cleanup. The forward code fix and the
+cleanup migration must ship **in the correct order** (see Sequencing).
+
+## Root cause (`syncSalesOrderFromNetsuite`, `library/app/api/toga2.php`)
+
+In the existing-customer-PO branch of `syncSalesOrderFromNetsuite()`, the reconciliation loaded and
+keyed existing PO lines **only by `vendorItem.item.uuid`**. A dual-catalog SKU (two `Items` rows,
+same `partNumber`, different `uuid`) whose fulfillment item resolved to the sibling `Item` produced
+no uuid hit → a new duplicate line + a shadow VendorItem, instead of re-linking the existing line.
+
+## The forward fix (already applied locally, uncommitted)
+
+`syncSalesOrderFromNetsuite()` gained a **`partNumber` (SKU) fallback** in the same branch:
+- Collect the relevant SKUs; a **second retrieval pass** fetches existing PO lines by
+  `Items.partNumber` and merges them (deduped) into the uuid lookup.
+- Build a `partNumber`-keyed lookup; the match block **falls back to it** after the two uuid
+  lookups, so an existing same-SKU line is **reused (re-linked)** instead of duplicated.
+- **VendorItem creation is gated to run ONLY when a new line is actually created** — a SKU match no
+  longer spawns a shadow VendorItem. (This was php-reviewer's critical regression check.)
+
+`php -l` clean; php-reviewer verified. Neither this edit nor the migration was committed this
+session — both are pending the developer's own deploy/commit.
+
+## The cleanup migration (`dbchanges2/Client_Compass/2026-07-22a - CleanupOfficeDepotDuplicatePurchaseOrderItems.sql`)
+
+**Deletion set (precisely defined):** a shadow-VendorItem line (cost 0) that has a **different
+non-shadow sibling** for the same `UPPER(partNumber)` on the **same PO**, on **`vendorId = 1`
+(Office Depot) POs only**. Validated in prod: all cost 0, **zero** customer-SO
+(`SalesOrderItems_PurchaseOrderItems`) links, and **zero** references from
+`AdvanceShippingNoticeItems` / `BillItems` / `ItemReceiptItems`.
+
+**FK deletion order (DELETE RESTRICT):** delete the two bridge tables
+(`PurchaseOrderItems_SalesOrderItems`, `SalesOrderItems_PurchaseOrderItems`) **before**
+`PurchaseOrderItems`.
+
+**Migration properties:** stages target ids into an audit table, prints a sanity count, wraps the
+deletes in a transaction, idempotent. `sql-reviewer` verified the logic and FK order.
+
+**Explicitly EXCLUDED from cleanup (left for manual review):** 412 both-shadow PO-SKU pairs, 39
+no-shadow pairs, the 3–4-shadow handful, non-Office-Depot vendors, and the shadow `VendorItems`
+rows themselves.
+
+## Sequencing (critical)
+
+**Deploy the code fix BEFORE running the cleanup.** Otherwise the next sync recreates the
+duplicates. Once the fix is live, the corrected sync re-links fulfillment SO items to the surviving
+lines by SKU.
+
+## Schema reference — tables that FK `Client_Compass.PurchaseOrderItems.id`
+
+Relevant to any PO-item deletion under DELETE RESTRICT (verified against prod schema): 7 tables —
+`AdvanceShippingNoticeItems`, `BillItems`, `ItemReceiptItems`,
+`PurchaseOrderItems_SalesOrderItems`, `PurchaseOrderItems_TransferOrderItems`,
+`SalesOrderItems_PurchaseOrderItems`, `TransferOrderItems_PurchaseOrderItems`. The TransferOrder
+bridges are empty for this deletion set; the two SalesOrder bridges are the only ones the shadow
+lines touch.
+
+## Change history
+- 2026-07-22 — Documented the dual-catalog (same-`partNumber`, two-`uuid`) duplicate OD PO-line
+  bug in `syncSalesOrderFromNetsuite` (uuid-only reconciliation; auto-created shadow VendorItems;
+  4,886 dup lines / 1,320 OD POs in prod), the forward SKU-fallback fix (second partNumber
+  retrieval + gated VendorItem creation), and the `2026-07-22a` cleanup migration (deletion set,
+  FK order, exclusions, deploy-fix-before-cleanup sequencing). Reference: SA133668 → OD PO
+  41342788-5125. Code + migration uncommitted, pending deploy. (jcardinal)
+</content>

package/knowledge/sessions/2026-07-22-compass-canada-french-localization-tcox.md

@@ -0,0 +1,78 @@
+---
+type: session
+slug: compass-canada-french-localization
+title: Compass Canada French localization — storefront done, persona DB backend deferred
+author: tcox
+repos: [toga2-commerce, dbchanges2, _underscore]
+framework: "2.0"
+client: compass-canada
+status: active
+created: 2026-07-22
+updated: 2026-07-22
+---
+
+# Session: compass-canada-french-localization
+**Date:** 2026-07-22
+**Project/Repo:** toga2-commerce (2.0), plus dbchanges2 + _underscore for the deferred backend
+**Task:** Finish Compass Canada French localization in the toga2-commerce storefront (Manage Requests, persona names, Account settings, Get Support, Kits, Open TOGa Supply, Orders for Others, order search, Get Support image) — frontend shipped; persona-name DB backend drafted but explicitly deferred.
+
+---
+
+## What WORKED
+- Account "Settings" tab → "Paramètres" and persona placeholder → "p. ex. Jean Tremblay" in all 4 French role files (`src/pages/Account/viewModel/FIELDS/COMPASSCANADA/FRENCH/<ROLE>/{ACCOUNTTABFIELDS,MYACCOUNTFIELDS}.json`). Evidence: JSON parse + EN/FR key-parity script passed.
+- Home page French: ADMIN file Kits→Trousses fixes (5 values); SUPERUSER `HOMEPAGEFIELDS.json` was mostly English and was fully rewritten to match USER/MANAGER French conventions; MANAGER itemsSection → "Articles". Evidence: parity + parse OK.
+- Hardcoded JSX keyed through HEADERFIELDS with in-code English fallbacks (COMPASS/QUAD unaffected): new `adminSubmenu.manageRequests` ("Gérer les demandes") and `alertsSubmenu.*` (markAllAsRead/openExternalLink/alertSingular/alertPlural/allUpToDate) in all 8 COMPASSCANADA HEADERFIELDS files; wired in `NavIconItem.tsx`, `AlertSubmenu.tsx` (+ `Submenus/types.ts`). Evidence: `npx tsc --noEmit` exit 0.
+- Orders for Others heading/subheading keyed (`ordersForOthersHeading`/`ordersForOthersSubheading`) and order search keyed (`pageSearchInput`) in ORDERHISTORYFIELDS (8 files); wired in `AccountPage.tsx` and `MyOrdersView.tsx`. French matches each role's existing phrasing style.
+- Get Support illustration switches by language: `GetSupportPage.tsx` uses `language?.startsWith("fr") ? get-support-img-french.svg : get-support-img.svg`; view model exposes `language`. Evidence: developer confirmed "Seeing it now".
+- Persona query cache fix: added `userPersonaDataOnLogin` + `userPersonaDataOnViewAs` to `LANGUAGE_SENSITIVE_QUERY_KEYS` in `src/queries/queries.ts` so persona names refetch on language switch.
+- Backend persona-translation artifacts drafted (5 files, see file table) — sql-reviewer verdict SAFE TO MERGE, 0 critical; reviewer's one warning (name-based JOIN) fixed by switching the 30 known personas to uuid-based JOIN.
+- Knowledge captured & pushed: CREATE `2.0/apps/_underscore/features/persona-name-translation.md` (status: draft), UPDATE `client-fields.md` (fr-CA correction), UPDATE compass-canada profile.
+
+## What did NOT work — DO NOT RETRY THESE
+- **`language === "fr"` comparison for French detection** — fails silently. The fields registry key and stored language value for COMPASSCANADA French is **`fr-CA`** (see `src/fieldsConfig/index.ts:909`; Account settings save stores the option uuid `en`/`fr-CA` via `setLanguage`). The team doc client-fields.md previously claimed `en`/`fr` — that was stale and is now corrected. Always use `startsWith("fr")`.
+- **Direct DB verification from this dev machine** — ALL endpoints timed out (connect ETIMEDOUT): `reader1.client.database.togahub.com`, `reader1.core.database.togahub.com`, both `production-*-global...rds.amazonaws.com` endpoints, `dev.sandbox.database.togahub.com`, and localhost MySQL (refused — none running). RDS clusters are VPC-restricted; needs VPN or the claude.ai "TOGa Database Integration" connector (not authorized in this session). A ready-to-run check script exists but the scratchpad is session-specific — recreate from the queries in the persona-name-translation.md doc.
+- **Seeding PersonaTranslations by joining on `Personas.name` for all rows** — sql-reviewer flagged it: `Personas.name` has no unique constraint, so a name join can fan out / mis-attach translations. Fixed: the 30 known personas join on `uuid`; only the 3 out-of-band personas (Admin Canada, MacBooks, Managers/VIPs) still match by name because their uuids exist only in the live DB.
+
+## Not tried yet (candidates for next session)
+- Run the DB pre-flight checks (needs VPN or TOGa DB connector): live `MAX(Core.Records.id)` must be 345 and `MAX(Core.RecordFields.id)` 2457 (migrations claim 346 / 2458-2462); `SELECT id,uuid,name,number FROM Personas ORDER BY id` on the Compass Canada client DB — confirm the 3 out-of-band personas exist and `GROUP BY name HAVING COUNT(*)>1` returns nothing; confirm `Languages` has `fr-CA`.
+- Confirm with the business whether the persona glossary has rows below "Managers/VIPs → Gestionnaires/VIP" (screenshot was cut off there) and extend the seed if so.
+- Commit/PR the frontend work (feature branch per git rules — never commit to `_main`); commit the backend files separately when un-deferred.
+- Visual verification pass against the developer's screenshots (was planned; not yet done in-session).
+- toga2-commerce full `npm run build` / smoke run (only `tsc --noEmit` was run).
+
+## Current file state
+| File | Status | Notes |
+|------|--------|-------|
+| toga2-commerce `.../FIELDS/COMPASSCANADA/FRENCH/<4 roles>/ACCOUNTTABFIELDS.json` | modified | Settings → Paramètres |
+| toga2-commerce `.../FRENCH/<4 roles>/MYACCOUNTFIELDS.json` | modified | persona placeholder French |
+| toga2-commerce `.../FRENCH/{ADMIN,SUPERUSER,MANAGER}/HOMEPAGEFIELDS.json` | modified | Trousses/Trousse; SUPERUSER fully retranslated |
+| toga2-commerce `.../COMPASSCANADA/{ENGLISH,FRENCH}/<4 roles>/HEADERFIELDS.json` | modified | + adminSubmenu, alertsSubmenu keys (8 files) |
+| toga2-commerce `.../COMPASSCANADA/{ENGLISH,FRENCH}/<4 roles>/ORDERHISTORYFIELDS.json` | modified | + ordersForOthers*, pageSearchInput (8 files) |
+| toga2-commerce `src/components/NavIcons/NavIconItem.tsx` | modified | labels from fields w/ fallbacks |
+| toga2-commerce `src/components/Submenus/AlertSubmenu.tsx` + `types.ts` | modified | 4 new optional label props |
+| toga2-commerce `src/pages/Account/AccountPage.tsx` | modified | orders-others heading from fields |
+| toga2-commerce `src/pages/Account/view/MyOrdersView.tsx` | modified | search label/placeholder from fields |
+| toga2-commerce `src/pages/GetSupport/GetSupportPage.tsx` + `viewModel/useGetSupportViewModel.ts` | modified | language-switched illustration |
+| toga2-commerce `src/queries/queries.ts` | modified | + 2 persona keys in LANGUAGE_SENSITIVE_QUERY_KEYS |
+| dbchanges2 `Client/2026-07-22a - PersonaTranslations.sql` | created — NOT run | sidecar DDL |
+| dbchanges2 `Core/2026-07-22a - PersonaTranslationsRecord.sql` | created — NOT run | record 346, fields 2458-2462, translation link |
+| dbchanges2 `Client/2026-07-22b - PersonaTranslationsAcl.sql` | created — NOT run | Base-role ACL chain |
+| dbchanges2 `Client_CompassCanada/2026-07-22a - PersonaTranslationsFrench.sql` | created — NOT run | fr-CA seed (30 by uuid + 3 by name) |
+| _underscore `Model/Client/PersonaTranslation.php` | created — NOT deployed | declarative sidecar model |
+
+## Decisions made
+- **Persona names translate server-side** via the metadata sidecar pattern (PersonaTranslations, mirror of AssortmentTranslations) — zero api2 code changes; rejected: client-side name mapping in the frontend (violates "business logic stays in API", wouldn't cover other consumers).
+- **Hardcoded JSX strings get FIELDS keys with in-code English fallbacks** so COMPASS/QUAD need no JSON changes; rejected: adding keys to every tenant's files (churn) or leaving literals (blocks localization).
+- **Header "Admin" stays "Admin" in French** — natural French abbreviation; "Administration" was applied then reverted at developer request.
+- **Backend/DB rollout DEFERRED** — developer decision 2026-07-22; frontend ships independently (fields labels French now; persona *values* go French when migrations run).
+- Identical-in-both-languages names (Servomax, ESFM, MacBooks…) are seeded anyway so the API translation layer finds sidecar rows instead of queueing missing-translation warnings.
+
+## Blockers
+- No network route to any TOGa RDS cluster from this dev machine (VPN needed), and the claude.ai "TOGa Database Integration" connector is unauthorized — blocks the pre-run DB verification for the persona migrations.
+- Persona glossary possibly incomplete (screenshot cut off after "Managers/VIPs").
+
+## Exact next step
+> When backend work resumes: connect VPN (or authorize the TOGa DB connector), run the three pre-flight queries in `knowledge/2.0/apps/_underscore/features/persona-name-translation.md` (next-free ids 346/2458-2462; the 3 name-matched personas + duplicate-name check; `fr-CA` in Languages), then commit the 4 dbchanges2 files + `_underscore/Model/Client/PersonaTranslation.php` on a `feature/persona-translations` branch. For frontend-only shipping: branch + PR the toga2-commerce changes listed above.
+
+---
+_Saved by /session-save on 2026-07-22_

package/package.json

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