toga-ai 1.0.753 → 1.0.754

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-09-01
+updated: 2026-09-02
 owners: [dfranks, jcardinal, kyalamarthi]
 files:
   - library/app/api/netsuite/rest.php
@@ -98,6 +98,21 @@ Forecast2 tables already store.
 - **TO_DATE rejects impossible dates** (e.g. `2026-06-31`) with an opaque HTTP 400 — validate
   calendar dates before building SuiteQL.
 
+- **⚠ SuiteQL returns date/datetime columns in the account DISPLAY format (here `M/D/YYYY`,
+  date-only) unless you wrap them in `TO_CHAR` — losing the time is silent (2026-09-02).** A bare
+  `SELECT lastmodifieddate` came back `9/2/2026` (no time, locale-dependent order), while
+  `TO_CHAR(lastmodifieddate,'YYYY-MM-DD HH24:MI:SS')` gave `2026-09-02 17:39:21`. Any shim that
+  **stores or compares a NetSuite date STRING** must `TO_CHAR(col,'YYYY-MM-DD HH24:MI:SS')` it, or it
+  drops the time and inherits the account's locale format. This defeated the per-client sync's
+  per-record resume cursor: it stored `9/2/2026|<id>`, sat at midnight, and re-scanned the whole day
+  every run — fixed by `TO_CHAR`-ing `lastmodifieddate AS lastmodifieddate` in the 8 cursor-feeding
+  SELECTs (`listSalesOrders`, `fetchSalesOrderByIdFull`, `listSales`, `listPurchaseOrders`,
+  `fetchPurchaseOrderById`, `listItemReceipts`, `listItemFulfillments`, `listInventoryAdjustments`).
+  `WHERE`/`ORDER BY` are unaffected by the alias — bound via `TO_TIMESTAMP` — so they still use the base
+  column. **Still latent:** `listOpportunities` and `listItems` return raw date-only `lastmodifieddate`
+  into their shims; harmless only because neither feeds a resume cursor yet. Engine-side detail on the
+  [per-client-sync doc](../../worker/features/netsuite-togasupply-per-client-sync.md).
+
 - **The line SuiteQL must SELECT the line location or it is always NULL — the shim reads it but
   didn't select it.** `listSalesOrders()`'s line query now selects `tl.location` and
   `BUILTIN.DF(tl.location) AS location_name`. The line-shim assembly code already *read* those two
@@ -275,6 +290,12 @@ None — uniform across clients (NetSuite is a single shared account).
 
 ## Change history
 
+- 2026-09-02 — Recorded that **SuiteQL returns date columns in the account DISPLAY format (date-only
+  `M/D/YYYY` here) unless wrapped in `TO_CHAR`** — a bare `lastmodifieddate` silently drops the time and
+  is locale-dependent. This defeated the per-client sync's per-record resume cursor (stored `9/2/2026|id`,
+  sat at midnight, re-scanned the whole day); fixed by `TO_CHAR(...,'YYYY-MM-DD HH24:MI:SS') AS
+  lastmodifieddate` in the 8 cursor-feeding SELECTs. `listOpportunities`/`listItems` still return raw
+  date-only but are latent (no cursor). (jcardinal)
 - 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

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

@@ -122,6 +122,35 @@ rename migration run on every client DB first (see the deploy-order gotcha below
   the same guarded `UPDATE ... WHERE key LIKE 'NETSUITE_LAST_SYNC_DATETIME_%'` so future new clients land on
   CURSOR keys. Still uncommitted in the working tree.
 
+### ⚠ The cursor was storing a date-ONLY, US-format value — the same-second tiebreak was dead (FIXED + DEPLOYED 2026-09-02)
+
+The per-record cursor "advanced" but its datetime half was `M/D/YYYY` with **no time** (e.g.
+`9/2/2026|6302323`), so it defeated its own same-second id tiebreak: the cursor sat at **midnight**,
+which no record's real timestamp equals, so every run re-fetched the **whole day** — the resume was
+defeated even while it looked healthy. Root cause: the SuiteQL SELECTs in
+`library/app/api/netsuite/rest.php` returned `lastmodifieddate` **raw**, and NetSuite hands that column
+back in the account **display** format (here `M/D/YYYY`, date-only). Proven: `SELECT lastmodifieddate`
+→ `9/2/2026`, but `TO_CHAR(lastmodifieddate,'YYYY-MM-DD HH24:MI:SS')` → `2026-09-02 17:39:21`. See the
+[SuiteQL/REST shim doc](../../library/features/netsuite-suiteql-rest-shim.md) for the general rule.
+
+- **Fix part 1 (`rest.php`):** wrapped the select as
+  `TO_CHAR(lastmodifieddate, 'YYYY-MM-DD HH24:MI:SS') AS lastmodifieddate` in the **8** SuiteQL SELECTs
+  that feed a cursor shim — `listSalesOrders`, `fetchSalesOrderByIdFull`, `listSales`,
+  `listPurchaseOrders`, `fetchPurchaseOrderById`, `listItemReceipts`, `listItemFulfillments`,
+  `listInventoryAdjustments`. `WHERE`/`ORDER BY` still use the **base** `lastmodifieddate` column (the
+  alias doesn't affect them) — the query bounds were already correct ISO via
+  `TO_TIMESTAMP('YYYY-MM-DD HH24:MI:SS')`.
+- **Fix part 2 (`common_sync_togasupply.php`):** normalized the datetime half at the **6** per-record
+  cursor PUTs to canonical `Y-m-d H:i:s` via `strtotime()` + `date()` (falls back to the raw string if
+  `strtotime` fails). The empty-window `"<windowTop>|0"` PUT was already canonical
+  (`App_Date::convertToSQLDate`).
+- **Old date-only cursors self-heal.** `strtotime('9/2/2026')` parses to midnight (one-time re-scan of
+  that day), then the next successful record overwrites with the full timestamp.
+- **LATENT (noted, not fixed):** `listOpportunities` and `listItems` in `rest.php` also return raw
+  date-only `lastmodifieddate` into their shims — harmless today because neither feeds a resume cursor,
+  but the same trap if either ever becomes one.
+- Deployed 2026-09-02 (worker + library re-deploy; both files had changed).
+
 ### ⚠ 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
@@ -1095,6 +1124,14 @@ the code deploy).
 
 ## Change history
 
+- 2026-09-02 — **Per-record cursor was storing a date-ONLY, US-format value — FIXED + DEPLOYED (shared:
+  `worker` + `library`).** The datetime half was `M/D/YYYY` with no time (e.g. `9/2/2026|6302323`), so the
+  cursor sat at midnight and the same-second id tiebreak never matched — every run re-fetched the whole day.
+  Root cause: `rest.php` SELECTed `lastmodifieddate` raw and NetSuite returns it in the account display format
+  (date-only here). Fixed by `TO_CHAR(lastmodifieddate,'YYYY-MM-DD HH24:MI:SS') AS lastmodifieddate` in the 8
+  cursor-feeding SuiteQL SELECTs, plus normalizing the 6 per-record cursor PUTs to canonical `Y-m-d H:i:s`
+  (`strtotime`+`date`, raw fallback). Old cursors self-heal (midnight → one re-scan → full timestamp).
+  `listOpportunities`/`listItems` share the raw-date trap but are latent (no cursor). (jcardinal)
 - 2026-09-02 — **Per-record resume cursor DEPLOYED to prod (shared: `worker` + `library` + `dbchanges2`).**
   Now live: worker commit `06e8f9ef` + library commit `3a70b59c` (tips of `_production`); rename migration
   `Client/2026-09-02b - NetsuiteSyncCursorRename.sql` run on all client DBs **before** the code. Recorded the

package/package.json

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