toga-ai 1.0.715 → 1.0.716

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-30
+updated: 2026-08-31
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -732,6 +732,35 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
   line). **Fix (`library`):** skip lines whose `adjustQtyBy` is null in **BOTH** passes over
   `inventoryList->inventory` (the item-build pass and the serial/unit pass). Shared fix; unblocked NYCHH
   inventory adjustments.
+- **⚠ Item-receipt sync froze on a PARTIAL receipt's NULL-quantity PO lines — the item-receipt TWIN of the
+  inventory-adjustment NULL-quantity fix above (fixed 2026-08-31).** For a partial item receipt NetSuite
+  returns **all** the PO's linked lines but sets `quantity=null` on the lines **not received on this
+  receipt** (SuiteQL `transactionline.quantity` is NULL for an un-received PO line). The REST shim
+  `App_Api_Netsuite_Rest::fetchItemReceiptById` (`rest.php` ~L2196) faithfully carries that null, and
+  `syncItemReceiptFromNetsuite` wrote those null lines into the `POST /v2/item-receipts` payload →
+  `ItemReceiptItems.quantity` is `NOT NULL` → api2 `EV-10` / MySQL **1048** "Column 'quantity' cannot be
+  null", the section threw (no per-record try/catch — fail-loud by design), and froze at `1-RUNNING`
+  re-trying the same poison receipt every 5 min. Seen on **NYCHH** ITEM_RECEIPTS: stuck on receipt **#22302**
+  (NetSuite internalId 3425518, dated 2023-05-01; 5 PO lines, 2 received qty 260, 3 returned null), watermark
+  frozen at 2023-05-01, throwing every run (`Logs.Issue 578`, "Invalid API Response" from
+  `send()` `toga2.php:3517`). **Fix (`library`):** skip line items whose `quantity` **`is_null`** (NOT
+  `empty`, so a legitimate received qty of 0 still writes) in **BOTH** passes over
+  `$nsItemReceipt->itemList->item` — the payload-build loop (~L3376) and the unit/serial pass (~L3538).
+  Shared fix; no signature change, no SQL. Recovery is automatic: the watermark sits at the failing window's
+  start, so on deploy the section self-heals (RUNNING→IDLE, watermark advances past #22302, window regrows).
+  Diagnosis chain (reinforces the playbook above): `Client_Nychh.Parameters` to localize the stuck section
+  (`1-RUNNING` + frozen watermark) → `Logs.Event` filtered by `clientId=3` for the crash file:line +
+  `transactionId` (`Logs.Event` carries `clientId`, `Logs.Issue` does not) → `Logs_Nychh.Api` on that
+  `transactionId` for the untruncated `EV-10`/1048 rejection and the payload showing the `quantity:null`
+  lines.
+- **⚠ OPEN, not yet root-caused (found 2026-08-31): NYCHH ITEM_FULFILLMENTS watermark frozen at 2021-12-29.**
+  `NETSUITE_EXECUTION_MODE_ITEM_FULFILLMENTS='3-IDLE'` with the window collapsed to ~3s (it has been
+  throwing recently) but currently **IDLE** — so it crawls a few seconds per run rather than sitting in a
+  hard `1-RUNNING` freeze. Distinct from the fixed ITEM_RECEIPTS freeze above; needs its own investigation.
+  Context: the 2026-08-31 full 19-client togasupply prod sweep found all other clients healthy
+  (`864000-IDLE`) except Elite SALES_ORDERS `864000-RUNNING` (healthy mid-run, large window, not stuck) and
+  AIG SALES_ORDERS `8-RUNNING` (the known held account, already documented). Only NYCHH ITEM_RECEIPTS was in
+  a true `1-RUNNING` freeze.
 - **⚠ Item-fulfillment stale-item prune must delete tracking-number children before the unit AND the item
   (fixed 2026-08-30).** In `syncItemFulfillmentFromNetsuite`'s cleanup loop, deleting a stale
   item-fulfillment-item-**unit** failed api2 `EV-11` / MySQL **1451** (FK
@@ -792,6 +821,16 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
 
 ## Change history
 
+- 2026-08-31 — **Item-receipt partial-receipt NULL-quantity fix (shared, `library`).**
+  `syncItemReceiptFromNetsuite` now **skips line items whose `quantity` is null** (unreceived PO lines on a
+  partial receipt) in both passes over `$nsItemReceipt->itemList->item` (payload-build ~L3376 + unit/serial
+  ~L3538), guarded on `is_null` so a received qty of 0 still writes. This is the item-receipt twin of the
+  2026-08-30 inventory-adjustment NULL-quantity skip — the receipt path never got that guard. It unfroze
+  NYCHH ITEM_RECEIPTS (stuck `1-RUNNING` on receipt #22302 / NetSuite 3425518 / 2023-05-01 → `EV-10`/1048
+  "quantity cannot be null", `Logs.Issue 578`); self-heals on deploy. Also flagged an OPEN item: NYCHH
+  ITEM_FULFILLMENTS watermark frozen at 2021-12-29 (`3-IDLE`, window collapsed to ~3s), not yet root-caused.
+  19-client sweep otherwise healthy. `library` only, no SQL, `php -l` clean; not deployed at capture time.
+  (jcardinal)
 - 2026-08-31 — **Invoice + serial-unit + duplicate-Item root-cause fixes (shared, `library`).**
   `syncInvoiceFromNetsuite` now assigns a **sequential 1..N invoice `lineNumber`** (NetSuite reuses `line`
   across multi-SO invoices → `InvoiceItems UNIQUE(invoiceId,lineNumber)` 1062 → atomic rollback → NYCHH

package/package.json

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