toga-ai 1.0.798 → 1.0.799

package/knowledge/1.0/apps/library/features/toga2-api-client-and-bridge.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-09-08
+updated: 2026-09-11
 owners: [jcardinal, mhammontree, bala]
 files:
   - library/app/api/toga2.php
@@ -79,6 +79,17 @@ belong to the NetSuite importer — documented in the per-client-sync doc, not h
 - Returns the decoded response object; callers read `->data->{resource}`, `->meta->nextPage`,
   `->isSuccess`, `->status`, `->messages[].code`.
 
+> **The "Invalid API Response" exception now LEADS with the api2 message codes (2026-09-11).**
+> `send()`'s failure exception used to `print_r` the whole response envelope, whose header prints
+> first — so on a real rejection the useful api2 code (e.g. `EV-10: ...`) fell **past** the
+> `Logs.Event.errorMessage` `varchar(255)` limit and was **truncated away**, making the failure look
+> "quiet" (this is exactly what hid the NYCHH duplicate-`Units` EV-10 — see the
+> [per-client sync doc](../../worker/features/netsuite-togasupply-per-client-sync.md)). The exception
+> message now puts the `->messages[].code: text` list **first**, via a new private helper
+> `describeApiMessages()` (~L726), then the `print_r` dump. The helper **caps each message's text at
+> 160 chars** so an echoed customer value cannot land in full in the log table (cso point). Net: the
+> real api2 cause self-reveals in `Logs.Event` on the next run instead of being cut off.
+
 > **`send()` ALWAYS returns something carrying `isSuccess` — so `empty($response->isSuccess)` is a
 > safe failure check on anything it returns, GETs included** (verified 2026-08-12, ~L432–450). It
 > returns early **only** when `isSuccess` is true; when `isSuccess` is false and
@@ -413,6 +424,15 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
 
 ## Change history
 
+- 2026-09-11 — **Observability: `send()`'s "Invalid API Response" exception now leads with the api2
+  message codes.** Added a private `describeApiMessages()` helper (~L726) that renders the
+  `->messages[].code: text` list (each text capped at 160 chars, cso point) and prepended it to the
+  exception message ahead of the `print_r` dump (~L636). Reason: `Logs.Event.errorMessage` is
+  `varchar(255)` and the old dump printed the envelope header first, pushing the real api2 code (e.g.
+  `EV-10`) past 255 chars where it was truncated — so failures looked "quiet". This made the NYCHH
+  duplicate-`Units` EV-10 self-reveal; the underlying case-mismatch fix and the three diagnosis traps
+  are on the [per-client sync doc](../../worker/features/netsuite-togasupply-per-client-sync.md). Library
+  only, `php -l` clean; **written, not committed/deployed**. (jcardinal)
 - 2026-09-08 - Added `updateTransferOrderStageToClosed(&$nsOrder, array &$clientConfiguration): bool`
   and the constant `TRANSFER_ORDER_STATUS__CLOSED = 'closed'` (also now used by the `case 'Closed'` in
   the transfer-order status switch). It is a **stage-only** writer: it never touches line items, so it

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-09-09
+updated: 2026-09-11
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -296,6 +296,49 @@ hit **every section and every client**, not just the by-reference ones.
   GET's UTC. `strtotime()` and `App_Date::convertToSQLDate()` both use the script tz (Chicago) and are
   the trap. Any manual cursor rewind value you set by hand must also be **Eastern**.
 
+### ⚠ ITEM_RECEIPTS froze at RUNNING on a case-mismatched Units serial → duplicate-unit INSERT (EV-10 / 1062) (found + fixed 2026-09-11, NYCHH prod)
+
+`syncItemReceiptFromNetsuite()` (`library/app/api/toga2.php` ~L4022) builds a PHP array of the
+client's existing `Units` keyed by **serial number** to decide PUT (update) vs POST (create). The
+DB `GET /units` (`Units.serialNumber IN (...)`) is **case-insensitive** and returns the **stored**
+casing (e.g. `'na100'`), but the code keyed the PHP lookup by that **raw stored** value while reading
+it with the **uppercased** serial (`strtoupper` at ~L3905). **PHP array keys are case-sensitive** → the
+lookup missed the existing row → took the **create** path → `POST /units` collided on the
+case-insensitive `Units.itemId_serialNumber` unique key → MySQL **1062** / api2 **EV-10** → the
+ITEM_RECEIPTS section **threw before its cursor PUT**, freezing at RUNNING (and ITEM_FULFILLMENTS,
+which runs behind it, froze with it).
+
+- **Proven on NYCHH:** `Client_Nychh.Units` 23400-23409 store serial `'na100'..'na109'` (lowercase),
+  `c_netsuiteInternalInventoryAssignmentId` NULL; the sync sent `'NA100'`.
+- **Fix (library only, `php -l` clean):** `strtoupper()` on **both** the array key **and** the reads,
+  so the PHP lookup is case-insensitive like the DB. A **second, half-fixed copy** of the same lookup
+  lower in the file (~L6326) already uppercased the **key** but not its two **reads** — made them
+  match too. php-reviewer + cso both cleared it (SAFE TO SHIP). **Written, NOT committed/deployed.**
+- **Lesson:** whenever a PHP lookup mirrors a case-insensitive DB column, normalize case on **every**
+  side — the key write and every read. One un-normalized read reintroduces the duplicate-create path.
+
+#### Diagnosis: three traps that hid this EV-10 (2026-09-11)
+
+The section looked "quiet" (RUNNING, no loud crash-loop under the usual filter) because of three
+things worth knowing for any 1.0-sync freeze:
+
+- **areaPath is NOT only `crons/toga2/netsuite`.** 1.0 sync NetSuite/api2 errors also log under
+  `context.REFERENCE.areaPath` = `library/app/api` and `library/app/api/netsuite` — filtering on the
+  cron path alone **misses** them. (The "Filter on areaPath = `crons/toga2/netsuite`" note near the top
+  of this doc is therefore an *incomplete* filter — widen it to these two areas as well.)
+- **EV-10 is api2's GENERIC "save failed" wrapper — the real DB error is NOT in base `Logs`.** The
+  underlying `1062 Duplicate entry ... for key ...` lives in `Logs_<Client>.Api`: filter
+  `responsePayload LIKE '%EV-10%'` (or join by `transactionId`) for route + `requestPayload` + the full
+  `responsePayload` carrying the real MySQL error. (Same `Logs_<Client>.Api` chain as the other rejection
+  gotchas in this doc.)
+- **Some crashes never record at all.** The worker's error-log write to the logs DB can time out
+  (`mysqli_select_db ... errno=110 Connection timed out`, e.g. `Logs.Issue` 588/589), so a section can
+  freeze with **no** `Logs.Event`/`Issue` row — read `Client_<X>.Parameters` for the stuck RUNNING
+  section as the primary signal, not the log tables.
+- Cross-link: the `send()` "Invalid API Response" exception was also changed 2026-09-11 to **lead with
+  the api2 message codes** so this EV-10 self-reveals in `Logs.Event` next time — see
+  [App_Api_Toga2](../../library/features/toga2-api-client-and-bridge.md).
+
 ### ⚠ Per-record isolation is SECTION-SPECIFIC — and SALES_ORDERS has NONE (corrected 2026-08-17)
 
 Whether a bad record is "stepped over" or freezes the section depends entirely on whether **that
@@ -1439,6 +1482,19 @@ library (or vice versa) crashes GroWrk and Adyen on their next sync run.
 
 ## Change history
 
+- 2026-09-11 — **ITEM_RECEIPTS froze at RUNNING on NYCHH: a case-mismatched `Units` serial lookup
+  (library, fix written not deployed).** `syncItemReceiptFromNetsuite` (`library/app/api/toga2.php`
+  ~L4022) keyed a PHP existing-`Units` array on the DB's stored serial casing (`'na100'`) but read it
+  with the uppercased serial (`'NA100'`, `strtoupper` ~L3905); PHP array keys are case-sensitive, so the
+  lookup missed the row, took the create path, and hit the case-insensitive `Units.itemId_serialNumber`
+  unique key → MySQL **1062** / api2 **EV-10** → the section threw before its cursor PUT and froze,
+  dragging ITEM_FULFILLMENTS behind it. Fixed by `strtoupper()`-ing **both** the array key and the reads
+  (and the half-fixed second copy ~L6326, which had the key but not its two reads). Proven on
+  `Client_Nychh.Units` 23400-23409 (serial `'na100'..'na109'`). php-reviewer + cso cleared it. Also
+  recorded the three diagnosis traps that hid it: sync errors also log under areaPath `library/app/api`
+  and `library/app/api/netsuite` (not only `crons/toga2/netsuite`); EV-10 is a generic wrapper whose real
+  1062 lives in `Logs_<Client>.Api` (`responsePayload LIKE '%EV-10%'`); and the worker's logs-DB write can
+  time out (errno 110, `Logs.Issue` 588/589) so some crashes never record. (jcardinal)
 - 2026-09-09 — **The resume cursor was READ on the wrong clock — a silent +1h window skip dropped
   records across ALL 6 sections and ALL clients (worker, deployed + verified).** `startModeIteration`
   (`common_sync_togasupply.php` ~L622) parsed the Eastern-stored cursor with `strtotime()` (script tz

package/knowledge/clients/nychh/profile.md

@@ -18,7 +18,7 @@ project: _Underscore
 client: nychh
 type: profile
 status: active
-updated: 2026-09-10
+updated: 2026-09-11
 owners: ["jcardinal", "apeterson", "bala", "akhokhani"]
 files:
   - dbchanges2/Client_Nychh/2026-09-02a - TransferOrderNetsuitePushInterceptor.sql
@@ -115,6 +115,16 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   written. Proven on IF `6138135` (Eastern 2025-09-04 17:26:58). Fixes and the standing "cursor is
   always Eastern" rule live in the
   [per-client sync feature doc](../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
+- **ITEM_RECEIPTS froze on a case-mismatched serial → duplicate-`Units` EV-10/1062, root-caused + fixed
+  (2026-09-11, fix NOT deployed).** The receipts feed threw before its cursor PUT (freezing it and
+  ITEM_FULFILLMENTS behind it) because `syncItemReceiptFromNetsuite` keyed its existing-`Units` PHP
+  lookup on the DB's stored serial casing (`'na100'`) but read it with the uppercased serial (`'NA100'`);
+  the missed row took the create path and collided on the case-insensitive `Units.itemId_serialNumber`
+  unique key → MySQL 1062 / api2 EV-10. Proven on `Client_Nychh.Units` 23400-23409
+  (serials `'na100'..'na109'`, `c_netsuiteInternalInventoryAssignmentId` NULL). Library-only fix
+  (`strtoupper()` on both the key and the reads). This is a **different** duplicate from the open
+  sales-order `Items` duplicate below (658-BFZH). Mechanism + the EV-10 → `Logs_Nychh.Api` diagnosis
+  traps: [per-client sync doc](../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
 - **NYCHH sync scope + data-gap scale + backfill approach (2026-09-09).**
   - **Scope = 22 NetSuite customers:** parent **28908** "NYC Health + Hospitals" + 21 hospital child
     customers (`24145, 29273, 29276, 31584, 31910-31916, 31918-31925, 32229, 33674`).

package/package.json

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