toga-ai 1.0.751 → 1.0.752

package/knowledge/1.0/apps/library/features/netsuite-sync-alert-monitor.md

@@ -104,18 +104,22 @@ that worker job does the syncing, this library class notices when it stops.
   checkpoints mean anything; and a client that is held / never transacts supply (AIG) must be
   left **off** this list or it produces permanent false-positive tickets.
 
-- **⚠ The pending cursor-rename in the sync will SILENTLY BLIND this monitor (BUILT 2026-09-02, not yet
-  deployed).** The per-record resume cursor work on the sync renames each section's position key from
-  `NETSUITE_LAST_SYNC_DATETIME_<SECTION>` to `NETSUITE_LAST_SYNC_CURSOR_<SECTION>` (value becomes
-  `"<lastmodifieddate>|<netsuite id>"`). This monitor's `NETSUITE_SYNC_PARAMETER_KEYS` still lists the old
-  `DATETIME` keys, so after the rename its `where..in` `/parameters` read matches **zero rows** and it
-  reports OK forever — no stale-checkpoint alerts. The sync developer **intentionally left the monitor
-  un-updated** this session (accepted gap). When the rename deploys, update `NETSUITE_SYNC_PARAMETER_KEYS`
-  to the `CURSOR` names **and** parse the `<date>|<id>` value (`strtotime` the part before `|`) before the
-  48h compare. See the [per-client sync doc](../../worker/features/netsuite-togasupply-per-client-sync.md).
+- **⚠ THIS MONITOR IS NOW BLIND — the cursor-rename shipped 2026-09-02 and this monitor was NOT updated.**
+  The sync's per-record resume cursor deployed to prod 2026-09-02 (worker `06e8f9ef` + library `3a70b59c`),
+  renaming each section's position key from `NETSUITE_LAST_SYNC_DATETIME_<SECTION>` to
+  `NETSUITE_LAST_SYNC_CURSOR_<SECTION>` (value now `"<lastmodifieddate>|<netsuite id>"`). This monitor's
+  `NETSUITE_SYNC_PARAMETER_KEYS` still lists the old `DATETIME` keys, so its `where..in` `/parameters` read
+  now matches **zero rows** and it reports OK forever — **no stale-checkpoint alerts fire**. This was an
+  accepted gap at deploy time, but it is now live. **FIX OWED:** update `NETSUITE_SYNC_PARAMETER_KEYS` to the
+  `CURSOR` names **and** parse the `<date>|<id>` value (`strtotime` the part before `|`) before the 48h
+  compare. See the [per-client sync doc](../../worker/features/netsuite-togasupply-per-client-sync.md).
 
 ## Change history
 
+- 2026-09-02 — **The sync's `NETSUITE_LAST_SYNC_DATETIME_*` → `NETSUITE_LAST_SYNC_CURSOR_*` rename SHIPPED to
+  prod (worker `06e8f9ef` + library `3a70b59c`), so this monitor is now BLIND** — its `where..in` read matches
+  zero rows and it reports OK forever. Monitor was not updated with the rename (accepted gap, now live). Fix
+  owed: update `NETSUITE_SYNC_PARAMETER_KEYS` to the CURSOR names + `strtotime` the part before `|`. (jcardinal)
 - 2026-09-02 — Flagged that the sync's pending `NETSUITE_LAST_SYNC_DATETIME_*` →
   `NETSUITE_LAST_SYNC_CURSOR_*` key rename (BUILT, not yet deployed) will make this monitor match zero rows
   and stop alerting; it was intentionally left un-updated. Update the key list + parse the `<date>|<id>`

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

@@ -92,12 +92,14 @@ its IDLE write. **There is no timeout, memory cap, or resource limit anywhere in
 never *tune the window size down*. (Corollary: a window that has grown back to the cap is positive
 evidence the section is completing.)
 
-### Per-record resume cursor — checkpoint after EACH record, not window-end (BUILT 2026-09-02, NOT yet deployed)
+### Per-record resume cursor — checkpoint after EACH record, not window-end (LIVE 2026-09-02)
 
 The historical weakness of window-end-only checkpointing: a mid-window crash (poison record, or the
 log-DB doom loop above) re-processes the **whole** window every run — the giant-fulfillment doom loop is a
 direct consequence. This change converts the checkpoint to **per-record keyset (seek) resume** so a
-transient crash resumes at the next record instead of redoing the window.
+transient crash resumes at the next record instead of redoing the window. **Deployed to prod
+2026-09-02** — worker commit `06e8f9ef` + library commit `3a70b59c` (both tips of `_production`), with the
+rename migration run on every client DB first (see the deploy-order gotcha below).
 
 - **Key rename per section:** `NETSUITE_LAST_SYNC_DATETIME_<SECTION>` → `NETSUITE_LAST_SYNC_CURSOR_<SECTION>`,
   value format **`"<lastmodifieddate>|<netsuite internal id>"`**. The id breaks same-second ties.
@@ -109,10 +111,16 @@ transient crash resumes at the next record instead of redoing the window.
   already carried it).
 - **Save after EACH main record** (one PUT of `lastmod|id`); on a clean window with 0 records, PUT
   `"<windowTop>|0"` so empty date ranges still advance. No new `try/catch` — stays fail-loud.
-- **Migration is MANDATORY with the code (see the reset trap in Gotchas):**
+- **Migration is MANDATORY, and runs BEFORE the code (see the deploy-order gotcha in Gotchas):**
   `dbchanges2/Client/2026-09-02b - NetsuiteSyncCursorRename.sql` (Client fan-out) renames the keys **and**
-  appends `|0` to carry the value across; safe to re-run. The new-client seed module
-  (`dbchanges2/_modules/netsuite/2026-08-05 - CLEAN NETSUITE CLINET.SQL`) was updated to CURSOR.
+  appends `|0` to carry the value across; safe to re-run. It was run on all client DBs first, then the
+  code deployed — the required order.
+- **⚠ OPEN follow-up — new-client seed was edited in place (dbchanges2 rule violation).** The seed module
+  `dbchanges2/_modules/netsuite/2026-08-05 - CLEAN NETSUITE CLINET.SQL` had its 6 seed rows **renamed in
+  place** to CURSOR keys with `|0`. That breaks the dbchanges2 "never edit an already-applied file" rule and
+  the client-schema drift audit. **Revert that file and add a NEW dated `_modules/netsuite/` file** carrying
+  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.
 
 ### ⚠ Per-record isolation is SECTION-SPECIFIC — and SALES_ORDERS has NONE (corrected 2026-08-17)
 
@@ -330,9 +338,11 @@ Per-client `Parameters` table (2.0 client DB, e.g. `Client_Canon.Parameters`; co
 
 Parameters are stored **per client DB** but accessed **through the TOGa2 API**, not direct SQL.
 
-**Pending rename (BUILT 2026-09-02, not yet deployed):** the position keys become
-`NETSUITE_LAST_SYNC_CURSOR_<SECTION>` with value `"<lastmodifieddate>|<netsuite internal id>"` — see the
-per-record resume cursor in *How it works*. The `NETSUITE_EXECUTION_MODE_*` keys are unchanged.
+**Key rename (LIVE 2026-09-02):** the position keys are now
+`NETSUITE_LAST_SYNC_CURSOR_<SECTION>` with value `"<lastmodifieddate>|<netsuite internal id>"` for all 6
+sections — see the per-record resume cursor in *How it works*. The `NETSUITE_EXECUTION_MODE_*` keys are
+unchanged. Renamed on every client DB by `Client/2026-09-02b - NetsuiteSyncCursorRename.sql` (run before
+the code deploy).
 
 ## Client variations
 
@@ -488,6 +498,19 @@ per-record resume cursor in *How it works*. The `NETSUITE_EXECUTION_MODE_*` keys
   `$dateField='lastmodifieddate'` and the engine calls it without the 4th arg. So a backdated
   `trandate` is irrelevant to whether an invoice imports, and a just-modified invoice still won't
   import until it is >24h old (the upper-bound cap).
+- **⚠ DEPLOY ORDER: the cursor-rename migration MUST run on EVERY client DB before the worker/library
+  deploy — there is NO old-key fallback in code.** `Client/2026-09-02b - NetsuiteSyncCursorRename.sql`
+  renames `NETSUITE_LAST_SYNC_DATETIME_<SECTION>` → `NETSUITE_LAST_SYNC_CURSOR_<SECTION>`. If the code
+  ships first, `startModeIteration()` reads a CURSOR key that doesn't exist yet and falls back to
+  `MIN_DATETIME_TO_CHECK_FOR_NETSUITE_DATA` (= `'2018-01-01'` for 17 of 18 clients) — re-scanning ~8 years
+  across all sections and all clients at once, a thundering herd against NetSuite + api2. Both the php and
+  sql reviewers flagged this as critical. The 2026-09-02 deploy followed the correct order (migration on all
+  client DBs first, then code). Same rule for any future position-key rename: schema first, code second.
+- **Per-record checkpoint PUT multiplies api2 round-trips on high-count catch-up windows (tuning note, not
+  shipped).** The per-record resume cursor does one `App_Api_Toga2::send` PUT per record. On a big backfill
+  window (e.g. sales orders / POs) that is one extra api2 round-trip per record. Optional future tuning:
+  batch the checkpoint every N records while still writing it **before** the next record's dispatch (so
+  crash-resume stays correct). Not built.
 - **A parse error in the shared `library/app/api/netsuite/rest.php` takes down EVERY client at
   once (tier-wide outage).** All wrappers autoload `App_Api_Netsuite_Rest` in the pre-section
   LOOKUPS/setup phase of `common_sync_togasupply.php` (~line 433). Because PHP parses the whole
@@ -1044,8 +1067,16 @@ per-record resume cursor in *How it works*. The `NETSUITE_EXECUTION_MODE_*` keys
 
 ## Change history
 
-- 2026-09-02 — **Per-record resume cursor BUILT (shared: `worker` + `library` + `dbchanges2`; pending
-  review + deploy, NOT shipped).** Converts the section checkpoint from window-end-only to per-record
+- 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
+  deploy-order rule (no old-key fallback — code-first would fall back to `MIN_DATETIME_TO_CHECK_FOR_NETSUITE_DATA`
+  = `'2018-01-01'` and thundering-herd re-scan ~8 years for all clients; php + sql reviewers flagged it
+  critical). Two open items: (1) the new-client seed `_modules/netsuite/2026-08-05 - CLEAN NETSUITE CLINET.SQL`
+  was edited in place (dbchanges2 rule violation) — revert + add a new dated file; (2) optional tuning — batch
+  the per-record checkpoint PUT every N records on high-count windows. Both still uncommitted. (jcardinal)
+- 2026-09-02 — **Per-record resume cursor BUILT (shared: `worker` + `library` + `dbchanges2`; shipped later
+  the same day — see entry above).** Converts the section checkpoint from window-end-only to per-record
   keyset resume so a mid-window crash (poison record or the log-DB doom loop) resumes at the next record
   instead of re-processing the whole window. Position key `NETSUITE_LAST_SYNC_DATETIME_<SECTION>` →
   `NETSUITE_LAST_SYNC_CURSOR_<SECTION>`, value `"<lastmodifieddate>|<netsuite id>"` (id breaks same-second

package/package.json

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