toga-ai 1.0.265 → 1.0.266

package/knowledge/2.0/apps/_underscore/INDEX.md

@@ -13,7 +13,7 @@
 | [_Model magic-field access (__get without __isset)](features/model-magic-field-access.md) | `_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`. | _underscore/Model/Core/Model.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php |
-| [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql |
+| [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql |
 | [Surface Resolver (_Model_Core_Surface::resolve — replaces Page::meta)](features/surface-resolver.md) | The runtime for the platform-wide **Surface** UI presentation layer: 9 `_underscore` models plus a cached resolver, `_Model_Core_Surface::resolve(&$api, string | _underscore/Model/Core/Surface.php, _underscore/Model/Client/AclRecordScript.php, _underscore/Model/Core/RecordScript.php, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Quad/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Client_CompassCanada/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, _underscore/Model/Core/SurfaceElement.php, _underscore/Model/Core/Action.php, _underscore/Model/Core/Vocabulary.php, _underscore/Model/Core/VocabularyTerm.php, _underscore/Model/Core/Message.php, _underscore/Model/Client/SurfaceOverride.php, _underscore/Model/Client/MessageTranslation.php, _underscore/Model/Client/ThemeToken.php, _underscore/Model/Core/Page.php |
 | [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | api2/Component/Api/V2/V2.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19b - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql |
 | [Units for Items for Purchase Orders — Data Structure](features/units-for-items-for-purchase-orders.md) | Describes how unit (serialized inventory) data is linked to sales-order and purchase-order line items behind the `units-for-items-for-purchase-orders` TableView |  |

package/knowledge/2.0/apps/_underscore/features/recursive-item-fulfillments.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-19
+updated: 2026-07-02
 owners: [jcardinal, rgirish]
 files:
   - _underscore/Model/Client/ItemFulfillment.php
@@ -16,6 +16,7 @@ files:
   - _underscore/Model/Compass/AdvanceShippingNotice.php
   - dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql
   - dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql
+  - dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql
 related:
   - ../architecture.md
   - ../../api2/architecture.md
@@ -102,12 +103,42 @@ inheritance. Verified against prod `Client_Compass` chains (≥3 levels deep).
   upstream mirror. A later reconciling PUT cleans up stale records via set comparison. Full
   delete handling would need a `preDelete` mechanism + `PRE/DELETE` interceptor rows.
 - **Transfer-order fulfillments are explicitly excluded from the upstream walk.** `reconcileUpstreamLevel()` returns `null` immediately when the downstream IF has `transferOrderId` set (no `salesOrderId`). This is intentional for standalone TOs (GroWrk v1). When SO→TO→SO chain scenarios are needed, Phase 5 of the GroWrk transfer order plan extends this method to walk `TransferOrders_SalesOrders` bridge tables — see `clients/growrk/features/transfer-order-flow.md`.
+- **Broken SOI↔POI bridge → empty header-only duplicate IFs (root cause, guard added
+  2026-07-02).** The item walk maps a downstream IFI up via
+  `IFI.salesOrderItemId → PurchaseOrderItems_SalesOrderItems → SalesOrderItems_PurchaseOrderItems`.
+  When that upstream `SalesOrderItems_PurchaseOrderItems` bridge is **missing/broken** (the same
+  integrity class as the ~116 off-by-one Compass orders — see the Compass
+  `asn-to-item-fulfillment` doc), `$desiredItems` resolves to **zero** even though the downstream
+  IF has items. Pre-guard, step 4's eager resolve-or-create then POSTed an **empty header-only
+  upstream IF** (e.g. Compass SA133377 got duplicate empty customer-facing IFs 71724/71725
+  alongside the legit direct-ASN IF 70635). **Guard:** `reconcileUpstreamLevel` now, after
+  building `$desiredItems`, if it is empty **AND** the downstream IF has >0 ItemFulfillmentItems,
+  `error_log()`s a diagnostic and returns `null` (skips the upstream mirror) — distinguished from
+  the legitimate header-first POST case (downstream IF genuinely has 0 items), which is unchanged.
+- **Duplicate customer-facing IF: the engine only adopts an upstream IF it created itself, never a
+  pre-existing one (known gap, adoption DEFERRED).** `reconcileUpstreamLevel` finds an existing
+  upstream IF only via `upstreamItemFulfillmentId`; it does **not** adopt a pre-existing IF that
+  already sits on the upstream SO from another flow (e.g. a direct-ASN-created IF). So a broken
+  bridge could yield two customer-facing IFs on the same SO (SA133377: direct-ASN IF 70635 + a
+  mirror-created duplicate). **Naive adoption is dangerous and was intentionally not implemented:**
+  step 5's delete-stale step deletes upstream IFIs with no matching downstream group, so adopting
+  an IF while the item walk is empty/broken would **DELETE the adopted IF's legitimate line items**.
+  Requires a CTO design review before implementing adoption semantics. The 2026-07-02 broken-bridge
+  guard prevents the duplicate cascade for this failure mode without needing adoption.
 - **Out of scope:** NetSuite sync of upstream IFs; transfer-order fulfillments
   (`transferOrderId`) are skipped.
 - **Performance:** every child write re-runs a full upstream walk (read-heavy, but each
   upstream record is written at most once — idempotent). Fine for normal fulfillment sizes.
 
 ## Change history
+- 2026-07-02 — Added a **broken-bridge guard** to `reconcileUpstreamLevel`: when `$desiredItems`
+  is empty but the downstream IF has items (broken SOI↔POI bridge), it logs and returns null
+  instead of creating an empty header-only duplicate upstream IF. Root-caused on Compass SA133377
+  (SO 107609), where a broken bridge + a pre-existing direct-ASN IF produced duplicate empty
+  customer-facing IFs (71724/71725) and left the correct serial/tracking off the customer IF;
+  data repaired by `dbchanges2/Client_Compass/2026-07-02a`. Companion fix — adopting a pre-existing
+  upstream IF instead of creating a duplicate — was **DEFERRED** pending CTO review (the delete-stale
+  step would delete the adopted IF's line items when the item walk is empty). (jcardinal)
 - 2026-06-19 — Documented explicit TO exclusion in reconcileUpstreamLevel; cross-linked GroWrk transfer order plan. (rgirish)
 - 2026-06-08 — Documented the Recursive Item Fulfillments engine (interceptor-driven upstream fulfillment mirroring, bundle scaling, reconcile loop). (jcardinal)
 

package/knowledge/2.0/apps/dbchanges2/architecture.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: architecture
 status: active
-updated: 2026-06-23
+updated: 2026-07-02
 owners: [jcardinal, mhammontree]
 files:
   - Core/
@@ -198,6 +198,41 @@ WHERE
 - Keep the single statement well under `max_allowed_packet` (64 MB default) — a few thousand
   rows is comfortably fine.
 
+## Self-referencing DELETE — wrap the subquery in a derived table
+
+MySQL forbids a `DELETE` (or `UPDATE`) whose `WHERE` subquery reads **the same table being
+modified** — it fails with **error 1093: "You can't specify target table 'X' for update in
+FROM clause."** This bites cleanup migrations that delete duplicate rows by selecting which
+rows to keep from the very table being pruned.
+
+The fix is to **materialize the subquery through an extra derived-table layer**, forcing MySQL
+to snapshot the row set before the delete runs:
+
+```sql
+-- WRONG — error 1093, ItemFulfillments is both the DELETE target and read in the subquery
+DELETE FROM ItemFulfillments
+WHERE id NOT IN (
+	SELECT MIN(id)
+	FROM ItemFulfillments
+	GROUP BY salesOrderItemId, trackingSerial
+);
+
+-- CORRECT — wrap the inner SELECT in a derived table so it is materialized first
+DELETE FROM ItemFulfillments
+WHERE id NOT IN (
+	SELECT keepId FROM (
+		SELECT MIN(id) AS keepId
+		FROM ItemFulfillments
+		GROUP BY salesOrderItemId, trackingSerial
+	) AS keep
+);
+```
+
+The extra `SELECT … FROM ( … ) AS keep` wrapper is the whole idiom: MySQL evaluates the inner
+query into a temporary derived table, so the outer `DELETE` no longer "sees" a live read of
+its own target. Used in `2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql` to prune
+duplicate `ItemFulfillments` rows.
+
 ## Relationship to the rest of 2.0
 
 `dbchanges2` is registered as a **2.0 core repo** (`role: core` in `registry.json`) — it is

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, _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, dbchanges2/Client_Compass/2026-06-18a - CleanupSA132898DuplicateTracking.sql, dbchanges2/Client_Compass/2026-06-18b - CleanupSA132881DuplicateTracking.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, dbchanges2/Client_Compass/2026-06-18a - CleanupSA132898DuplicateTracking.sql, dbchanges2/Client_Compass/2026-06-18b - CleanupSA132881DuplicateTracking.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.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 MITS PO Transmission to Vendors](features/mits-po-transmission-to-vendors.md) | 2.0 | The 1.0 worker cron `2_transmit_mits_purchase_orders_to_vendors.php` transmits Compass PurchaseOrders to their vendors (Office Depot, Strategic Systems, Compass | worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, library/app/client/compass.php |

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

@@ -5,7 +5,7 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-06-30
+updated: 2026-07-02
 owners: [jcardinal, bala]
 files:
   - _underscore/Model/Compass/AdvanceShippingNotice.php
@@ -18,6 +18,7 @@ files:
   - dbchanges2/Client_Compass/2026-06-16c - BackfillSA132763C40QYUCTracking.sql
   - dbchanges2/Client_Compass/2026-06-18a - CleanupSA132898DuplicateTracking.sql
   - dbchanges2/Client_Compass/2026-06-18b - CleanupSA132881DuplicateTracking.sql
+  - dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql
 related:
   - ../../../2.0/apps/_underscore/features/recursive-item-fulfillments.md
   - ../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
@@ -207,6 +208,18 @@ Compass Canada (`Model/Compass/Canada/`) is a separate sub-client. The Compass c
 
 ## Change history
 Dated one-liners, newest first.
+- 2026-07-02 — Repaired SA133377 (SO 107609, line 1 MD7F4LL/A-S): the customer IF (IFI 276821)
+  had no serial and the wrong tracking (`522944658493` — the first of two tracking-only vendor
+  ASNs on PO 103641 that reconciled onto the direct-ASN IF 70635) instead of `873840444805`
+  (the real device unit 63108 / serial SKRX9Y4W537 arrived up the mirror chain from downstream
+  IF 71723). Migration `2026-07-02a` adds the missing IFIU + correct unit-level tracking, swaps
+  the stale header/item tracking, and retires the empty duplicate IF 71725 (idempotent, sql-reviewer
+  SAFE). Root cause was a broken `SalesOrderItems_PurchaseOrderItems` bridge on the downstream
+  shipped SO item (PO item 179306, no upstream bridge — same off-by-one integrity class as the
+  ~116 orders above) feeding the recursive mirror engine, which then created empty duplicate
+  customer-facing IFs; forward engine guard added in the
+  [Recursive Item Fulfillments](../../../2.0/apps/_underscore/features/recursive-item-fulfillments.md)
+  doc (2026-07-02). (jcardinal)
 - 2026-06-30 — `resolveOrCreateItemFulfillment` now resolves the shipped `ItemFulfillmentStage` by
   status slug and sets `itemFulfillmentStage` on the IF payload, so ASN-created fulfillments land
   shipped (not stage-less) on both Compass USA + Canada. Part of the platform-wide IF stage

package/package.json

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