toga-ai 1.0.141 → 1.0.142

package/knowledge/2.0/apps/worker2/features/netsuite-salesorder-open-orders-sync.md

@@ -100,6 +100,26 @@ None — uniform (platform-wide Forecast2 sync).
   handler sees them). NB: `App_ApiTransaction::execute(false)` returns a raw JSON **string** for a record
   GET — `json_decode` it directly; double-encoding it (`json_decode(json_encode($resp))`) silently yields
   an empty object and a false "empty record" reading.
+- **REST `item.items` sublist has read-after-write LAG → partial or empty syncs that freeze (this is the deeper root of the gotcha above).** The handler builds `OpenOrderItems` from the REST record GET's
+  `item.items` sublist, and that sublist **trails the committed record for seconds after edits** — it can
+  return *fewer lines than the order actually has*. Because `syncOpenLines` reconciles to exactly what it
+  read (upsert + delete-not-returned), a lagged read commits a **partial** line set (N of M) or an **empty**
+  one (0 of 1), and it **freezes there** — no later webhook fires to correct it, so the only repair is a
+  re-sync/trueup. **Confirmed live 2026-06-18 on SO 7170669** (tranId 279851): 14 PUT jobs ran **strictly
+  sequentially on one instance, in order** (`dtStarted`/`instanceId` proven — *not* concurrent, *not*
+  out-of-order); the **last** (authoritative) read at 18:03:49 committed **4 lines**, while the order has
+  **15** ($4,634 of $8,714 — short $4,080). A later REST GET returned all 15 (the sublist had caught up),
+  and SuiteQL `transactionline` showed 15 throughout. SO 7152319 is the 0-of-1 form. **Ruled OUT:**
+  concurrency/ordering (jobs were serial on one instance) and enqueue/drain (jobs all `isSuccess=1`) — so
+  "trust the current REST state" fails specifically because the REST *sublist isn't reliably current*.
+  **Fix direction (not yet implemented):** source the open lines from **SuiteQL `transactionline`** (which
+  was consistent exactly when the REST sublist lagged — same query `probe_open_order_lines.php` uses)
+  rather than the REST `expandSubResources` sublist; *or* re-read until the line count is stable before
+  committing. A `lastModifiedDate` freshness/ordering guard does **NOT** help — it isn't an ordering bug.
+  The fix **must stay real-time** — do **not** defer to the 15-min cron (see the AMQ real-time constraint /
+  `project_amq_realtime_requirement` in dev memory). Diagnose with `probe_open_order_lines.php` (SuiteQL vs
+  Forecast) + `probe_so_rest_lines.php` (live REST sublist count) + the `WorkerJobs` `dtStarted`/`instanceId`
+  timing (to confirm serial-vs-concurrent before blaming ordering).
 - **REST shape ≠ SOAP shape.** The cron reads the SOAP-shim shape; this handler reads the REST record
   (`status->refName`, line `quantityBilled`, `class->refName`, `entity->id`, `salesRep->id`,
   `shippingCost`). Verified against live orders via `test/@dave/probe_salesorder_rest_shape.php`.
@@ -154,6 +174,15 @@ and are a candidate to extract into a shared `_Component_Forecast_Db` before the
 
 ## Change history
 
+- 2026-06-18 — **Root-caused the open-order delta to REST `item.items` read-after-write lag** (not the
+  drainer/enqueue fixes, not ordering). SO 7170669 committed 4 of 15 open lines despite 14 *strictly
+  sequential, single-instance, in-order* PUTs — the last authoritative read returned a lagged partial
+  sublist; REST later caught up to 15 and SuiteQL showed 15 throughout. Disproved the earlier
+  out-of-order/concurrency hypothesis (verified via `WorkerJobs.dtStarted`/`instanceId`) and a
+  `lastModified` ordering guard (irrelevant — reads were in order). Fix direction recorded: source open
+  lines from **SuiteQL `transactionline`** instead of the REST sublist (or re-read until line count is
+  stable), keeping the path real-time (no cron deferral). New diagnostic: cross-check
+  `probe_open_order_lines.php` (SuiteQL) vs `probe_so_rest_lines.php` (REST sublist). (dfranks)
 - 2026-06-18 — **Verified live in production** after the SalesOrder enqueuer left Testing. 14 orders
   reconciled against NetSuite SuiteQL (`probe_open_order_lines.php`); 13 at $0.00 delta. Found one
   miss — SO 7151688 (open, ~$20.31, 0 rows) — traced to the **async-recalc race** above (see new

package/package.json

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