toga-ai 1.0.416 → 1.0.418

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/features/approval-decision-flow.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-07-17
-owners: ["apeterson", "dfranks"]
+updated: 2026-07-23
+owners: ["apeterson", "dfranks", "bala"]
 files:
   - _underscore/Model/Compass/ApprovalDecision.php
   - _underscore/Model/Compass/SalesOrder.php
@@ -50,11 +50,35 @@ tenants differ, the **parent** branches on `$api->client->clientIdentifier === '
 - **Email-template resolution** — `resolveEmailTemplateUuid()` picks the tenant's template UUID.
 - **EN/FR localization** — user language is read from `UserGlobalSettings` (`settingId = 2`;
   `en` / `fr-CA`) so Canadian notifications go out in the recipient's language.
+- **Web-link host resolution** — `_Model_Compass_SalesOrder::resolveSupplyHost()` /
+  `resolveCommerceHost()` pick the tenant's supply/commerce domain for the links embedded in
+  approval and order-status emails (see below).
 
 Because the divergence is a runtime branch and not an override, do **not** add per-client logic to
 the empty subclasses — extend the shared parent and branch there if a genuine tenant difference is
 needed.
 
+### Email-link host resolution (US vs Canada domains)
+The "Review Order" link (togasupply) and the user order-details link (togacommerce) embedded in
+Compass approval and order-status emails are built from a **client-aware host resolver** on the
+shared parent `_Model_Compass_SalesOrder`, so the link always points at the domain that actually
+holds the order:
+- Four host constants: `HOST_SUPPLY__COMPASS_US = 'compass.togasupply.com'`,
+  `HOST_SUPPLY__COMPASS_CANADA = 'compasscanada.togasupply.com'`,
+  `HOST_COMMERCE__COMPASS_US = 'compass.togacommerce.com'`,
+  `HOST_COMMERCE__COMPASS_CANADA = 'compasscanada.togacommerce.com'`.
+- Public static `resolveSupplyHost(&$api)` / `resolveCommerceHost(&$api)` return the correct host;
+  private static `isCompassCanadaClient(&$api)` returns
+  `($api->client->clientIdentifier ?? '') === 'Compass_Canada'`. Anything not Canada falls back to
+  the **US** host, so US behavior is unchanged.
+- All 8 link-building sites build the URL as `"https://" . resolveSupplyHost($api) . "/?..."` (only
+  the host varies; the query string / uuid is identical). Sites wired: `ApprovalDecision.php` —
+  manager-approval-request block and VIP auto-approve block (`orderUrl` + `userOrderUrl` in each);
+  `SalesOrder.php` — admin-approved block (`postPut`), in-transit/delivered block, and
+  `_sendVipManagerNotification`.
+- This reuses the **same `$api->client->clientIdentifier` signal** as the email-template language
+  resolver, so the link host and the email template can never disagree.
+
 ### VIP manager auto-approve — the rule and its three (all supervisor-derived) triggers
 A single rule governs VIP auto-approve: a **manager-stage (step 2)** approval auto-approves iff the
 assigned manager's `Users.c_isVip = 1` **AND** the order subtotal
@@ -114,8 +138,25 @@ requester**. All of these comparisons are case-insensitive (`strcasecmp()`), mat
   requester/new-manager guards.
 - **Don't put tenant behavior in the empty subclasses.** `Usa`/`Canada` `ApprovalDecision` are
   intentionally empty; the tenant branch lives in the parent on `clientIdentifier`.
+- **Never hardcode the web host in email links.** The email links previously used string literals
+  `compass.togasupply.com` / `compass.togacommerce.com` in the parent classes. Because the tenant
+  subclasses are empty, **Compass Canada orders inherited the US links** and sent Canada
+  recipients to the US supply/commerce site, which does not contain their order — so the link never
+  opened. Always build the host via `_Model_Compass_SalesOrder::resolveSupplyHost()` /
+  `resolveCommerceHost()`, never a literal. Real incident: order SAC100650 — manager Gary Berenz
+  could not open the order from the "Manager Approval Needed" email, so admin Kai Wong had to
+  approve as manager on his behalf. (Fixed 2026-07-23.)
 
 ## Change history
+- 2026-07-23 — Fixed Compass approval/status **email links** being hardcoded to the US domains
+  (`compass.togasupply.com` / `compass.togacommerce.com`) in the parent classes, so Compass Canada
+  orders (empty `Canada` subclass) inherited US links and Canada recipients were sent to a site
+  without their order. Added a client-aware host resolver to `_Model_Compass_SalesOrder` (four
+  `HOST_*` constants, `resolveSupplyHost()`/`resolveCommerceHost()`, `isCompassCanadaClient()`
+  branching on `clientIdentifier === 'Compass_Canada'`, US fallback), and rewired all 8 link sites
+  in `ApprovalDecision.php` and `SalesOrder.php` to build the host through it — reusing the same
+  `clientIdentifier` signal as the email-template resolver so host and template always agree.
+  Verified both client contexts resolve correctly; `php -l` clean. Prod incident SAC100650. (bala)
 - 2026-07-17 — Documented the VIP manager auto-approve rule (VIP manager + subtotal ≤ $5000) and
   its three supervisor-derived triggers (`postPost` creation, `postPut` contact change,
   `handleManagerReassignment` on `postPut`), plus the **POST-path gap**: a requester with no

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/package.json

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