toga-ai 1.0.729 → 1.0.731

package/knowledge/1.0/apps/library/features/netsuite-suiteql-rest-shim.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-30
+updated: 2026-09-01
 owners: [dfranks, jcardinal, kyalamarthi]
 files:
   - library/app/api/netsuite/rest.php
@@ -169,6 +169,19 @@ Forecast2 tables already store.
   cross-checking item id, then number each line by the NetSuite `line` (fall back to `linesequencenumber`
   if the item ids disagree). Self-heals on the next receipt sync (it re-imports the PO). Same "join a
   NetSuite line on `line`, not `linesequencenumber`" lesson as the `tl.id` semantics above.
+- **⚠ `listPurchaseOrders()` scoped POs by the VENDOR header `entity`, silently dropping every
+  drop-ship PO for all clients (fixed 2026-09-01).** It reused the shared `buildEntityInFilter()`
+  helper — correct for `listSalesOrders`/`listSales` (SO header `entity` = customer) but **wrong for
+  POs**, whose header `entity` is the **vendor**. The `AND entity IN (<customer ids>)` filter matched
+  ZERO customer POs, so the header query returned nothing and the section imported nothing — no error.
+  Replaced with a new `buildPurchaseOrderCustomerFilter()` that scopes by the customer on the LINES or
+  the end-customer body field:
+  `AND ( id IN (SELECT tl.transaction FROM transactionline tl WHERE tl.entity IN ($ids) AND tl.mainline = 'F') OR CUSTBODY_END_CUSTOMER IN ($ids) )`.
+  `buildEntityInFilter()` is unchanged. This is a **fetch-scope** bug (record never returned by the
+  `list*`), a class distinct from the per-id `fetchPurchaseOrderById` shim-shape gaps above — but the
+  same underlying trap of reusing a sales-order-shaped assumption on a purchase order. Full
+  engine-side impact + the tier-wide per-client backfill live on the
+  [per-client-sync doc](../../worker/features/netsuite-togasupply-per-client-sync.md).
 - **A shim must produce the SOAP object's SHAPE, not just its scalar fields — an absent nested list
   crashes 1.0 (2026-08-29).** `fetchCustomerById()`'s `addressbookList` was where the AIG lookup phase
   crashed: a REST customer with no/odd address made the shim omit the nested `addressbook` structure the
@@ -262,6 +275,14 @@ None — uniform across clients (NetSuite is a single shared account).
 
 ## Change history
 
+- 2026-09-01 — Recorded that **`listPurchaseOrders()` scoped POs by the VENDOR header `entity`** (via
+  the reused `buildEntityInFilter()`), silently dropping every drop-ship / special-order PO for all
+  togasupply clients since the SOAP→REST migration. A PO header `entity` is the vendor, not the
+  customer, so `AND entity IN (<customer ids>)` matched zero rows and the section imported nothing with
+  no error. Fixed by a new `buildPurchaseOrderCustomerFilter()` that scopes by the line-level customer
+  or `CUSTBODY_END_CUSTOMER` body field; `buildEntityInFilter()` untouched. Fetch-scope bug (distinct
+  from the per-id shim-shape gaps). Engine impact + per-client backfill on the per-client-sync doc.
+  (jcardinal)
 - 2026-08-30 — Recorded that **`fetchPurchaseOrderById` numbered PO lines by `linesequencenumber` instead
   of the NetSuite `line`** — a receipt for a post-gap line (PO with a deleted middle line, real lines
   1,2,4) failed `EV-12` "unable to find a unique match" (GroWrk PO 168223). The PO record line sublist

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

@@ -389,6 +389,47 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
   skipped; and because the location filter is shared, receipts belonging to **other** clients at a
   shared warehouse are returned and correctly skipped. Modelling receipts as "location-matched"
   produces wrong diagnostics.
+- **⚠ The PURCHASE_ORDERS section silently dropped EVERY drop-ship / special-order PO on ALL
+  togasupply clients — a PO header `entity` is the VENDOR, not the customer (fixed 2026-09-01).**
+  `App_Api_Netsuite_Rest::listPurchaseOrders()` (`library/app/api/netsuite/rest.php`) scoped the PO
+  HEADER query with `AND entity IN (<client customer ids>)` via the shared `buildEntityInFilter()`
+  helper. That helper is correct for **sales** orders (an SO header `entity` IS the customer) but
+  **wrong for POs** — a PO header `entity` is the **vendor**. So the customer-id filter matched ZERO
+  of a client's POs, the `foreach` never ran, and there was **no interest check, no throw, no log** —
+  a pure fetch-scope miss. Proven on Elite PO tranid 128238 (NS internal 5412515, customer 36443,
+  vendor TD Synnex 20202): `... AND entity IN (36443)` returned 0 rows; unfiltered returned 1;
+  filtering by LINE entity (`transactionline.entity IN (36443)`) returned 1.
+  - **Why drop-ship POs vanished ENTIRELY (two-path gap).** Two import paths reach a PO and both
+    excluded drop-ship: (a) the dedicated PURCHASE_ORDERS section, via the header-entity filter above;
+    (b) the nested `syncItemReceiptFromNetsuite → syncPurchaseOrderFromNetsuite` path (via
+    `fetchPurchaseOrderById`, which has **no** entity filter) never fires for a drop-ship PO because a
+    drop-ship PO produces item **fulfillments**, not item **receipts**. Stock POs still imported via
+    the item-receipt path — which is why Elite had 51 NS POs (all stock, from the 2026-08-12 backfill)
+    yet was missing drop-ship ones like 128238. Drop-ship POs carry `customForm.internalId = 148`
+    ("ASI - Drop Ship Purchase Order"), the end customer on the transaction LINES
+    (`transactionline.entity`) and on `shipTo`, so the dedicated PURCHASE_ORDERS section is their
+    **only** import path.
+  - **Fix (library only, no SQL, no other repos):** added
+    `private static function buildPurchaseOrderCustomerFilter(array $entityInternalIds): string` and
+    switched `listPurchaseOrders()` to use it. It scopes POs by the customer on the LINES or the
+    end-customer body field instead of the vendor header:
+    `AND ( id IN (SELECT tl.transaction FROM transactionline tl WHERE tl.entity IN ($ids) AND tl.mainline = 'F') OR CUSTBODY_END_CUSTOMER IN ($ids) )`.
+    `buildEntityInFilter()` is left **untouched** (still correct for `listSalesOrders`/`listSales`/
+    `listItemFulfillments`, where header entity = customer). Empty-ids behavior preserved (returns
+    `''` = no scoping). Deployed; PO 128238 then imported for Elite (dev confirmed). **PO fetch must
+    scope by line-level customer / end-customer, never the vendor header entity — the opposite of the
+    sales-order shape, and the reason the reused helper silently lost data.** Cross-ref: the sibling
+    per-id path's own shim gaps are in the
+    [SuiteQL/REST shim doc](../../library/features/netsuite-suiteql-rest-shim.md).
+  - **⚠ Tier-wide backfill owed, per-client.** Because `listPurchaseOrders` is shared, EVERY
+    togasupply client has been missing its drop-ship POs since the SOAP→REST migration. Backfill each
+    client by rewinding `NETSUITE_LAST_SYNC_DATETIME_PURCHASE_ORDERS` (idempotent) — do it
+    **deliberately, one client at a time**, not all at once (Elite's first window 2024-04-15..04-18
+    alone held 269 POs).
+  - **Diagnostic lesson (durable):** a "silent, no-error, not-imported" record in this engine can be a
+    **fetch-scope mismatch** (the record is never returned by `list*`), distinct from a per-record
+    throw. The `$isInterested == 1` you see when feeding a single PO directly (or via the diagnose
+    script) can disagree with the scheduled section, which never fetched it.
 - **`Units.locationId` is never populated by this sync — transaction location lives on the item
   rows.** All 229 `Client_Elite.Units` have `locationId` NULL. `locationId` exists only on `Units`
   and `InventoryAdjustmentItems` (not on the `*ItemUnits` bridge tables), and

package/knowledge/clients/compass-usa/workflows/catalog-fold-reversal.md

@@ -6,7 +6,7 @@ client: compass-usa
 type: workflow
 status: active
 updated: 2026-09-01
-owners: ["jcardinal"]
+owners: ["jcardinal", "bala"]
 files:
   - test/team/2.0 deployment/duplicate_items_merge_ALL_CLIENTS.sql
   - test/team/2.0 deployment/duplicate_items_merge_analysis.sql
@@ -59,6 +59,15 @@ NULL-catalog junk items** and **199 duplicate-Agilant items** (from the NetSuite
 inventory-adjustment item-create bug). **Only the 199 catalog-1 → catalog-2 folds were the
 damage.**
 
+**⚠ Open contradiction — not resolved, do not assume either side.** Folding by
+`UPPER(partNumber)` requires those 199 pairs to have **shared a part number across catalogs**
+pre-merge, and the reversal restored them. But a prod check of `Client_Compass` on **2026-09-01**
+found **zero part numbers duplicated at all, and zero spanning more than one catalog**. Both
+statements cannot be true of prod today. Re-check on prod whether the restored catalog-1 twins
+carry **distinct** part-number variants (the `#B1H` / `-S` forms) or genuinely-shared ones before
+relying on either the 199 figure or table-wide `partNumber` uniqueness. Same flag from the other
+side: [two-catalog item model](../features/item-catalogs-and-duplicate-items.md).
+
 ## The reversal playbook (durable)
 
 1. **Restore a pre-merge snapshot as a scratch DB** — e.g. `Client_Compass_20260831_120000`
@@ -127,6 +136,10 @@ catalog-1 items were folded into catalog-2 **AND** storefront/transmit depends o
 NULL-`assetType` order lines alone are **not** damage (Prudential and Quad show that as normal).
 
 ## Change history
+- 2026-09-01 — Flagged (did **not** resolve) the contradiction between this doc's 199
+  shared-`UPPER(partNumber)` catalog-1→catalog-2 folds and the same-day prod verification that zero
+  Compass part numbers span two catalogs; mirrored from the item-catalogs doc so it is visible from
+  both sides. (bala)
 - 2026-09-01 — **Blast-radius assessment complete.** Resolved the outstanding per-client
   assessment: only **2 of 17** clients were damaged — Compass (reversed prior session) and Quad
   (storefront-only, reversed this session). The other 15 needed no reversal: 13 single-catalog

package/knowledge/clients/compass-usa/workflows/odp-order-pipeline-to-netsuite.md

@@ -160,7 +160,8 @@ Cron 3a resolves each line through that SKU when the `VA` text does not match th
    **onto the ODP SalesOrder (customerId=1), never the Compass SO (customerId=2)**.
    **Exclusion filters** (an order legitimately waiting is not a bug):
    - `CompassSalesOrders.number NOT LIKE 'MA%'` — MA orders are excluded.
-   - the two-part **release gate** below (this is the "30-minute delay").
+   - the two-part **release gate** below (usually releases on the **next 10-minute run**; the
+     30-minute timeout is the fallback, not the normal path).
    - **computer-kit orders** (Bundles 187–196) wait for a **2nd PO** before syncing. This one is
      **not** in the `WHERE` clause — it is a per-row check run in PHP *after* the query
      (`Bundles.number IN (192, 187, 188, 195, 193, 189, 194, 190, 191, 196)`, then a count of that
@@ -182,6 +183,19 @@ holds (verified against the cron source 2026-08-28, the `WHERE` block around `:9
   created at least **30 minutes** ago (`IFNULL(MIN(OfficeDepotPO.dtCreated), NOW()) <=
   DATE_SUB(NOW(), INTERVAL 30 MINUTE)`), in which case it transmits with whatever has come back.
 
+**⚠ Branch (a) is the normal path — do NOT expect a 30-minute wait.** (a) is satisfied the instant
+every expected Office Depot PO has arrived, so a straightforward order transmits on the **very next
+`*/10` run**, typically **within ~2 minutes** of the ODP PO being created. The 30-minute timeout is
+the **exception**, reserved for orders where something never comes back (see the mixed buy-from-ODP
+case below). Verified on prod (2026-09-01): ODP POs created 14:50-14:55 on 2026-08-31 transmitted at
+14:57-14:58; ODP PO `41850937-5125` created `2026-09-01 13:18:20` transmitted at `13:20:46`
+(NetSuite SO `7441681`).
+
+**Why this matters when triaging:** if you assume half an hour is normal, a genuinely stalled
+transmission looks fine for 30 minutes. It is not. An order that has all its 850s back and is still
+untransmitted **two `*/10` runs later** is already abnormal — go look at the bridge rows
+(`PurchaseOrders_SalesOrders` / `SalesOrders_PurchaseOrders`) rather than waiting.
+
 **Cron 5 never opens an EDI file and never looks in S3.** It infers that the 850 arrived purely from
 the **link rows cron 3a writes**: Compass PO → `PurchaseOrders_SalesOrders` → Office Depot SO →
 `SalesOrders_PurchaseOrders` → Office Depot PO. If 3a did not write the bridges, cron 5 cannot tell
@@ -210,10 +224,12 @@ order never reached NetSuite," and it is not.
 `7437998` / `7437898` / `7438098`. Only after that check is "it never reached NetSuite" a real
 finding.
 
-**⚠ Do not infer the schedule from transmission times.** Transmissions cluster at **:00 and :30**,
-which reads like a 30-minute cron — it is not. The schedule is **`*/10`** (re-verified in
-`worker/schedules/cron.worker.sync.json` on 2026-08-28); the clustering is the 30-minute **release
-gate** above, not the cadence.
+**⚠ Do not infer the schedule from transmission times.** Some transmissions cluster at **:00 and
+:30**, which reads like a 30-minute cron — it is not. The schedule is **`*/10`** (re-verified in
+`worker/schedules/cron.worker.sync.json` on 2026-08-28); that clustering is the timeout branch of
+the **release gate** above firing on the orders that can only release that way, not the cadence.
+Orders released by branch (a) do **not** cluster — they land on whichever `*/10` run follows their
+last 850 (e.g. `13:20:46`).
 
 ### ⚠ Office Depot only sends an 850 back for what they buy FROM us
 
@@ -356,6 +372,11 @@ wrong record makes every order look "stuck." Use the **join**, never a number ma
   transmission feature.)
 
 ## Change history
+- 2026-09-01 — **Corrected the expected cron 5 timing:** release branch (a) ("every expected ODP
+  PO has arrived") is the **normal** path and fires on the next `*/10` run (~2 min), so the
+  30-minute timeout is the exception, not the rule — previously this doc read as if 30 minutes were
+  the standard delay. Prod evidence: 2026-08-31 POs created 14:50-14:55 transmitted 14:57-14:58; ODP
+  PO `41850937-5125` created 13:18:20 transmitted 13:20:46 (NetSuite SO `7441681`). (bala)
 - 2026-09-01 — Added the diagnostic that the **Office Depot PO number lands in NetSuite's
   `otherRefNum`, which global search does not index** — searching it finds nothing even on an order
   that transmitted fine, so open the SO by `c_netsuiteInternalSalesOrderId` off the ODP SO

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

@@ -6,8 +6,8 @@ project: Worker
 client: elite
 type: client-feature
 status: active
-updated: 2026-08-12
-owners: ["snaredla"]
+updated: 2026-09-01
+owners: ["snaredla", "jcardinal"]
 files:
   - worker/crons/toga2/netsuite/sync_togasupply_elite.php
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -125,6 +125,17 @@ the trait declares must exist as a column, a `CustomRecordFields` row **and** an
 
 ## Change history
 
+- 2026-09-01 — **Drop-ship / special-order POs were never importing for Elite** (e.g. PO tranid
+  128238). Root cause was in shared code, not Elite: `listPurchaseOrders()` filtered the PO header by
+  the VENDOR `entity` (TD Synnex 20202) instead of the customer, so Elite's 36443-scoped filter matched
+  0 POs, and drop-ship POs — which make item fulfillments, not receipts — had no other import path.
+  Fixed engine-side (new `buildPurchaseOrderCustomerFilter()` scoping by line-level customer /
+  end-customer); PO 128238 then imported (dev confirmed). Full write-up on the
+  [engine doc](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md) and
+  [SuiteQL/REST shim doc](../../../1.0/apps/library/features/netsuite-suiteql-rest-shim.md). Elite's
+  older stock-only PO count (51) will grow once its `NETSUITE_LAST_SYNC_DATETIME_PURCHASE_ORDERS` is
+  rewound to backfill drop-ship POs (idempotent; first 2024-04-15..04-18 window alone held 269 POs).
+  (jcardinal)
 - 2026-08-12 — TRUE-80499: **onboarded Elite to the NetSuite → TOGa Supply importer.** Built the
   wrapper (customer 36443, `isParentCustomer` false, 30-day window, invoices temporarily disabled),
   the schedule entry, 18 `_Model_Elite_*` netsuite trait models, the `_modules/netsuite` opt-in, and

package/package.json

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