toga-ai 1.0.730 → 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/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.730",
+  "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",