toga-ai 1.0.760 → 1.0.761

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

@@ -202,6 +202,43 @@ Prudential-EDI, S&P Global**.
 - **Lesson:** any `sync*FromNetsuite()` that takes the record `&$byReference` and refetches must have
   its fetch-by-id shim carry **every** field the caller reads afterward — `lastModifiedDate` first.
 
+### ⚠ …but the by-reference shim wrote the cursor on the WRONG CLOCK → ITEM_RECEIPTS + ITEM_FULFILLMENTS re-matched forever (found + fixed 2026-09-03, NYCHH prod)
+
+A follow-on to the by-reference fix directly above. Once the two shims carried a `lastModifiedDate`
+again, the sections still could **not advance** — the value was in the **wrong timezone**, so
+`lastmodifieddate > cursor` re-matched the **same record every run** (an infinite loop, no crash).
+
+- **Root cause — two clocks.** The prior fix set `fetchItemFulfillmentById` / `fetchItemReceiptById`'s
+  `->lastModifiedDate` from the **REST record GET**, which returns **UTC** (e.g. `2024-08-06T14:45:00Z`).
+  `common_sync_togasupply.php` then `date()`-formats it in the script timezone **America/Chicago** →
+  `2024-08-06 09:45:00`, and stores that as the cursor. But the LIST fetch's `WHERE`
+  (`App_Api_Netsuite_Rest::listItem*`) compares `lastmodifieddate` via SuiteQL
+  `TO_CHAR(lastmodifieddate,'YYYY-MM-DD HH24:MI:SS')`, which is the **NetSuite account timezone =
+  Eastern** → `2024-08-06 10:45:16`. So the cursor was written **~1 hour behind** the clock the fetch
+  reads → `lastmodifieddate > cursor` was always still true for the record just processed → it was
+  re-fetched and re-processed forever and the watermark never moved.
+- **Proven on NYCHH prod** (item receipt internalId `4953915`): REST GET `lastModifiedDate`
+  `2024-08-06T14:45:00Z` (UTC) · SuiteQL `2024-08-06 10:45:16` (Eastern) · stored cursor
+  `2024-08-06 09:45:00` (Chicago). ITEM_RECEIPTS was jammed on it; because that heavy receipt (nested
+  PO→SO reconcile) runs **before** fulfillments and starved the run, ITEM_FULFILLMENTS' window kept
+  collapsing to 6s and never grew to clear the empty gap to its first real record (2025-01-06; 1,294
+  NYCHH fulfillments waited after 2025-01-01).
+- **INVENTORY_ADJUSTMENTS was NOT stuck** — `fetchInventoryAdjustmentById` already reads
+  `lastmodifieddate` from SuiteQL `TO_CHAR` (the right clock), so it advanced normally. **That is the
+  correct pattern**; the other two shims did not follow it.
+- **Fix (library only, `php -l` clean, fail-loud preserved):** in `library/app/api/netsuite/rest.php`,
+  `fetchItemFulfillmentById` (~L2093) and `fetchItemReceiptById` (~L2254) now set
+  `$shim->lastModifiedDate` from a SuiteQL
+  `SELECT TO_CHAR(lastmodifieddate,'YYYY-MM-DD HH24:MI:SS') AS lastmodifieddate FROM transaction WHERE id = $id`
+  (Eastern) — matching `fetchInventoryAdjustmentById` — **instead of** the REST header's UTC
+  `$header->lastModifiedDate`. No shim reads the REST/UTC `lastModifiedDate` anymore. No worker change,
+  no SQL. After deploy the two sections resume and backfill on their own (idempotent).
+- **Lesson:** the per-record cursor value MUST be written in the **same timezone the fetch `WHERE`
+  compares against** — SuiteQL account time (Eastern), never the REST record GET's UTC
+  `lastModifiedDate`. A cursor even an hour behind the fetch clock re-matches the same record forever.
+  This is the same SuiteQL-vs-REST clock trap as the date-only-format bug above — see the
+  [SuiteQL/REST shim doc](../../library/features/netsuite-suiteql-rest-shim.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
@@ -1175,6 +1212,15 @@ the code deploy).
 
 ## Change history
 
+- 2026-09-03 — **By-reference shim wrote the cursor on the WRONG CLOCK → ITEM_RECEIPTS + ITEM_FULFILLMENTS
+  re-matched the same record forever (fixed, `library` only).** Follow-on to the same-day by-reference
+  fix below: the shims set `lastModifiedDate` from the REST GET (UTC), `date()`-formatted in
+  America/Chicago, but the LIST `WHERE` compares SuiteQL `TO_CHAR(lastmodifieddate)` in the NetSuite
+  account tz (Eastern), so the cursor sat ~1h behind the fetch clock and `lastmodifieddate > cursor`
+  always re-matched — infinite loop, no crash. `fetchItemFulfillmentById`/`fetchItemReceiptById`
+  (`rest.php` ~L2093/~L2254) now read `lastmodifieddate` from SuiteQL `TO_CHAR` (Eastern), matching
+  `fetchInventoryAdjustmentById` (already correct). Proven on NYCHH prod (item receipt 4953915). No
+  worker/SQL change; sections self-backfill after deploy. (jcardinal)
 - 2026-09-03 — **By-reference refetch dropped `lastModifiedDate` → ITEM_FULFILLMENTS + INVENTORY_ADJUSTMENTS
   froze (fixed, `library` only).** GroWrk's ITEM_FULFILLMENTS was re-throwing every 5 min since the
   2026-09-02 per-record cursor deploy (`Undefined property: stdClass::$lastModifiedDate` at

package/package.json

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