toga-ai 1.0.99 → 1.0.100

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

@@ -2,7 +2,7 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
-| [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, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql, dbchanges2/Client_Compass/2026-06-15b - BackfillSA132781ItemFulfillmentTracking.sql |
+| [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 |
 | [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 |
 | [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 USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |

package/knowledge/clients/compass-usa/features/asn-to-item-fulfillment.md

@@ -5,13 +5,17 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-06-15
+updated: 2026-06-16
 owners: [jcardinal]
 files:
   - _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
 related:
   - ../../../2.0/apps/_underscore/features/recursive-item-fulfillments.md
 ---
@@ -143,9 +147,43 @@ Compass Canada (`Model/Compass/Canada/`) is a separate sub-client. The Compass c
   number) straight into queries. These are now passed through `_Database::escape()`.
 - Separate latent bug in the 1.0 worker: the Strategic Systems cron's no-serials branch
   builds `$itemLevelTrackingNumbers` but never attaches it to the ASN payload.
+- **Cross-line tracking contamination from bad SOI↔POI bridge rows (root cause, fixed
+  forward 2026-06-11):** `postPost` resolves which IFI(s) a tracking number attaches to by
+  joining `AdvanceShippingNoticeItems → SalesOrderItems_PurchaseOrderItems → SalesOrderItems`.
+  It trusts that bridge completely, so a wrong bridge row silently sends one ASN's tracking
+  onto an unrelated part's IFI. Two distinct pre-fix bugs produced bad bridge rows on Compass
+  SA orders: (1) `_Model_Compass_PurchaseOrder` linked SO↔PO items by matching
+  `SalesOrderItems.lineNumber = PurchaseOrderItems.lineNumber` — but a PO item's lineNumber is
+  **PO-local** (each PO starts at 1), so when one SO is split across multiple POs the PO line
+  numbers collide with unrelated SO lines (e.g. SA132743: PO `50305071-1` line 1 = 910-006272
+  wrongly linked to SO line 1 = C40QYUC). Fixed in `_underscore` commit `ec935478` (2026-06-11,
+  "Only link SO/PO items for MR orders") — the lineNumber join is now MR-only; SA orders link
+  via `createdFromSalesOrderItem` (item identity). (2) The 1.0 worker cron
+  `3a_import_office_depot_purchase_orders.php` paired API-returned PO items to SOIs by array
+  index, producing off-by-one neighbor links (fixed forward to pair by lineNumber; see
+  SA132763 cleanup file header). **Diagnosing:** a bridge row is provably wrong when its
+  `SalesOrderItems.itemId <> VendorItems.itemId` (the linked SOI's product differs from the PO
+  item's actual product). The `2026-06-16*` cleanup migrations delete exactly those rows plus
+  the tracking they spilled, scoped to one order.
+- **Retroactive cleanup MUST be paired with a backfill — a cleanup-only repair leaves the
+  line blank.** Removing the *wrong* tracking from a contaminated IFI does not restore the
+  *correct* one: the correct number often never reached the IF side (the SO was fulfilled
+  out-of-band before the 2026-06-15 reconcile fix, and the cleanup adds nothing). The original
+  `2026-06-16 - CleanupSA132763CrossLineTracking.sql` was cleanup-only and left C40QYUC on
+  SA132763 with no tracking at all; `2026-06-16c` backfilled it. When repairing an order, also
+  backfill each affected IFI's correct tracking (the tn carried by an ASN item whose
+  `VendorItems.itemId` matches the IFI's SOI item) at both item and package level, guarded by
+  `NOT EXISTS`. ~116 PO items across other Compass orders share the off-by-one fingerprint and
+  are not yet repaired — a broader reviewed backfill is still outstanding.
 
 ## Change history
 Dated one-liners, newest first.
+- 2026-06-16 — Identified cross-line tracking contamination root cause: bad
+  `SalesOrderItems_PurchaseOrderItems` rows (PO-local lineNumber collision in
+  `_Model_Compass_PurchaseOrder`, fixed forward 2026-06-11 `ec935478`; and the worker ODP-PO
+  cron's array-index pairing). Repaired SA132743 (`2026-06-16b`, cleanup + backfill) and
+  backfilled SA132763's C40QYUC (`2026-06-16c`) after finding the `2026-06-16` SA132763 cleanup
+  was cleanup-only and left the line blank. (jcardinal)
 - 2026-06-15 — `postPost` + helpers refactored so **UUID is the reference field**, dropping all
   reliance on the integer `id` returned from `internalApiRequest` (not always present). Helper
   returns are uuid-only; `$trackingTargets`/`$packageTrackingByItemFulfillment` are uuid-keyed;

package/package.json

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