toga-ai 1.0.136 → 1.0.137

package/knowledge/2.0/apps/worker2/INDEX.md

@@ -8,5 +8,5 @@
 | [Elite Freshservice Sync (worker2)](features/elite-freshservice-sync.md) | `_Worker_Elite` processes Freshservice webhook events and syncs them into TOGA 2. | worker2/Worker/Elite.php, worker2/Config/dev-kmaramreddy-laptop.ini |
 | [Monitoring Framework (Orchestrator + Child Monitors)](features/monitoring-framework.md) | A unified, DB-driven monitoring framework for business-critical data flows (Compass POs, Prudential asset imports, AIG closed claims, …). | worker2/Worker/Monitor.php, worker2/Worker/Monitors/, worker2/Worker/Notification/Email.php, dbchanges2/Core/2026-05-21 - Monitors.sql |
 | [NetSuite → TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, test/@dave/probe_clickup_desc_match.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
-| [NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)](features/netsuite-salesorder-open-orders-sync.md) | Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). | worker2/Worker/Netsuite/SalesOrder.php, worker2/Worker/Netsuite.php, test/@dave/probe_salesorder_rest_shape.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
+| [NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)](features/netsuite-salesorder-open-orders-sync.md) | Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). | worker2/Worker/Netsuite/SalesOrder.php, worker2/Worker/Netsuite.php, test/@dave/probe_salesorder_rest_shape.php, test/@dave/probe_open_order_lines.php, test/@dave/check_so_status.php, test/@dave/check_so_history.php, test/@dave/probe_so_rest_lines.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [Teams Meeting Transcript Export](features/teams-transcript-export.md) | `_Worker_Team_Transcripts` (action `Team/Transcripts/Export`) polls Microsoft Graph for Teams meeting transcripts produced by a set of organizers, classifies ea | worker2/Worker/Team/Transcripts.php, worker2/Config/production.ini |

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

@@ -6,12 +6,16 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-17
+updated: 2026-06-18
 owners: ["dfranks"]
 files:
   - worker2/Worker/Netsuite/SalesOrder.php
   - worker2/Worker/Netsuite.php
   - test/@dave/probe_salesorder_rest_shape.php
+  - test/@dave/probe_open_order_lines.php
+  - test/@dave/check_so_status.php
+  - test/@dave/check_so_history.php
+  - test/@dave/probe_so_rest_lines.php
   - worker/crons/toga2/forecast2/import_open_orders.php
   - worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php
 related:
@@ -77,6 +81,25 @@ None — uniform (platform-wide Forecast2 sync).
 
 ## Gotchas / known issues
 
+- **Async-recalc race → a transiently-empty REST read PURGES a genuinely-open order (silent data loss).**
+  The open-status gate is not the only way rows get deleted: on an **open** order, if the REST GET
+  momentarily returns **zero importable open lines**, `syncOpenLines` runs its reconcile-delete with an
+  empty kept-set and wipes every existing row — there is no separate "removeAll", but the effect is the
+  same. This fires when NetSuite's own **asynchronous `-System-` line recompute** (e.g. the open
+  gross-profit pass, `CUSTCOL_OPEN_GP`) is still in flight at the instant the webhook's REST GET runs —
+  the record reads back open but with its open lines not yet materialized. The webhook is often *triggered
+  by that very recompute*, so the GET races it. **Confirmed live 2026-06-18 on SO 7151688** (tranId
+  279345): 4 edit webhooks at 14:02:35–48 CDT all succeeded with **0 rows**, while NetSuite's `-System-`
+  open-GP recompute wrote the line values at the same 14:02:30–45 window (NS Eastern = worker Central +1h).
+  A manual re-sync 22 min later imported all 4 lines correctly. Nothing self-heals it — there is no retry,
+  and the batch cron is being decommissioned. **Fix direction (not yet implemented):** never let "open
+  status + zero importable lines" trigger a destructive delete — re-fetch after a short delay, or treat it
+  as retryable (`throw` → `isSuccess=0` → re-runs) — and only let a **confidently-closed** status
+  (Billed / Closed / Cancelled) purge. Diagnose with `check_so_history.php` (systemnote status timeline)
+  + `check_so_status.php` (current REST status) + `probe_so_rest_lines.php` (REST `item.items` as the
+  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 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`.
@@ -131,6 +154,15 @@ and are a candidate to extract into a shared `_Component_Forecast_Db` before the
 
 ## Change history
 
+- 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
+  gotcha): the order was approved (Pending Approval → Pending Fulfillment) *before* the enqueuer was
+  released (so the approval itself never enqueued — one-time cutover artifact), then NetSuite's
+  `-System-` open-GP recompute fired the edit webhooks and the handler's REST GET raced that recompute,
+  reading zero open lines → reconcile-delete. A manual re-sync corrected it. Added diagnostics
+  `check_so_status.php`, `check_so_history.php`, `probe_so_rest_lines.php`. No code change yet — fix
+  direction recorded in the gotcha. (dfranks)
 - 2026-06-17 — **Fixed dropped zero-revenue/open-cost lines.** REST omits `rate` for $0 lines, and the
   `if (!is_numeric($rate)) continue;` guard was skipping them — but the cron inserts these (profit =
   −qtyOpen × unitCost; 575 such rows in prod). Now defaults missing/non-numeric rate to 0 so the both-zero

package/package.json

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