toga-ai 1.0.591 → 1.0.592

package/knowledge/1.0/apps/library/features/error-capture-1-0.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-04
+updated: 2026-08-17
 owners: ["jcardinal", "mhammontree"]
 files:
   - library/app/error/capture.php
@@ -177,6 +177,15 @@ exists in `api2`/`worker2`. So 1.0 reads the AL1 container config at
 
 ## Gotchas / known issues
 
+- **⚠ A grouped `Logs.Issue` row can show a STALE error id — read the live api2 transaction log for
+  the current error.** Two facts combine to mislead: (1) `Event.errorMessage` is **`varchar(255)`**,
+  so a long API response is **truncated** — often before the trailing error id; and (2)
+  `Logs.Issue.subject` / `Issue.errorMessage` hold the **first-occurrence** text, so a long-lived
+  issue keeps showing the error id from whenever it was first seen even after the per-call error has
+  changed. Observed 2026-08-17: issue `3H` still displayed `EO-1` / `3G-6` (the original
+  undefined-method fatal) while the current per-call failure was actually `EV-11` (an FK 1451 on a
+  DELETE). **To see what is failing *now*, read the live api2 transaction log
+  (`Logs_<client>.Api.responsePayload`) for the specific call — not the grouped `Issue` row.**
 - **Any PHP warning inside capture code would kill the request.** 1.0's
   `App_Error::handleError()` routes **every** PHP warning into `handleException()`, which renders
   the red box and calls `exit()` — so a single warning raised while capturing (an unreachable IMDS
@@ -220,6 +229,12 @@ exists in `api2`/`worker2`. So 1.0 reads the AL1 container config at
 
 ## Change history
 
+- 2026-08-17 — Recorded a diagnostic trap: a grouped `Logs.Issue` row can show a **stale error id**
+  because `Event.errorMessage` is `varchar(255)` (truncates a long API response, often before the
+  error id) and `Issue.subject`/`errorMessage` keep the **first-occurrence** text — observed issue
+  `3H` still showing `EO-1`/`3G-6` while the live per-call error was `EV-11` (FK 1451). Read the live
+  `Logs_<client>.Api.responsePayload` for the actual current error. Surfaced diagnosing the Compass
+  USA NetSuite SO sync freeze. (jcardinal)
 - 2026-08-05 — Recorded the legacy `DELETE_DOA_PRE-SENTRY_error.php` handler leaking the full
   config array (prod DB / SES / NetSuite / Payeezy / SSL Store credentials + ticket PII) on a
   live towfoundation.togaview.com error page, meaning that host evaluates as dev mode in

package/knowledge/1.0/apps/library/features/toga2-api-client-and-bridge.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-10
+updated: 2026-08-17
 owners: [jcardinal, mhammontree, bala]
 files:
   - library/app/api/toga2.php
@@ -328,6 +328,16 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
   **and** the consuming code. (The general 2.0-side metadata behavior — reverse relations resolved via
   the child model's `FOREIGNKEY_MODEL` and named as the camelCase plural of the child model — is a
   framework-level fact captured separately.)
+- **⚠ Depth alone does NOT return every reverse-hasMany collection — `GET /sales-orders` at depth 4
+  omits `itemFulfillmentItems` and `invoiceItems`.** Verified 2026-08-17 against prod
+  `Logs_Compass.Api` responses (no fields whitelist): a depth-4 sales-order GET returns
+  `salesOrderItems` and the **PO-link bridge** collections
+  (`salesOrderItemPurchaseOrderItems`, `purchaseOrderItemSalesOrderItems`) but **not**
+  `itemFulfillmentItems` or `invoiceItems`. So any importer code that guards on
+  `$salesOrderItem->itemFulfillmentItems` / `->invoiceItems` from that GET is a **silent no-op** —
+  same reverse-hasMany trap as above, now with a concrete consequence: the NetSuite SO renumber fix
+  keys off a recorded "could-not-delete" set instead of trusting those collections (see
+  [NetSuite → TOGa Supply per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md)).
 - **`TOGA_AIG.Customers.emailAddress` is `varchar(255)`** (V1 legacy, latin1_swedish_ci) — wide
   enough to hold several `'; '`-joined emails, so TRUE-79401 needed **no** schema/dbchanges migration
   (the earlier fear that it was ~VARCHAR(55) was wrong) — but **it is a real ceiling: ~6–7
@@ -386,6 +396,13 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
 
 ## Change history
 
+- 2026-08-17 — Recorded that **depth-4 `GET /sales-orders` omits the `itemFulfillmentItems` and
+  `invoiceItems` reverse-hasMany collections** (it does return `salesOrderItems` and the PO-link
+  bridges), verified against prod `Logs_Compass.Api` — so code guarding on those collections from
+  that GET is a silent no-op, reinforcing the reverse-hasMany-fields trap. Surfaced fixing the
+  NetSuite SO renumber freeze (Compass USA), which now keys off a recorded "could-not-delete" set;
+  see [NetSuite → TOGa Supply per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md).
+  (jcardinal)
 - 2026-08-12 — Recorded the **`send()` return contract**: it always returns a response carrying
   `isSuccess` (early-returns on true, falls through to `return $response` on false, throws when the
   property is absent), so `empty($response->isSuccess)` is a safe failure check on anything it

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-12
+updated: 2026-08-17
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -87,13 +87,28 @@ 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.)
 
-### ⚠ A per-record API failure does NOT stop the cursor — the record is skipped forever
-
-The cursor write (`LAST_SYNC_DATETIME_*`) and `finishModeIteration()` both run **unconditionally
-after** the record loop. A record that throws mid-loop is captured to Sentry and **stepped over**,
-while the section still reports success and advances the cursor past its window. So
-**"section IDLE + cursor advancing" is not proof of a complete import** — it only proves the run
-didn't die.
+### ⚠ 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
+section's** record loop wraps the `sync*FromNetsuite()` call in a per-record `try/catch`. It is not
+uniform across the six sections, and the earlier blanket claim here ("a per-record failure does not
+stop the cursor — the record is skipped forever") is **false for the SALES_ORDERS section**.
+
+- **Where a section DOES isolate per record:** the cursor write (`LAST_SYNC_DATETIME_*`) and
+  `finishModeIteration()` run after the loop, so a caught record is skipped and the section still
+  reports IDLE and advances. There, **"section IDLE + cursor advancing" is not proof of a complete
+  import** — it only proves the run didn't die (recovery = rewind the cursor; re-import is
+  idempotent).
+- **⚠ SALES_ORDERS has NO per-record `try/catch`.** The `SALES_ORDERS` foreach in
+  `common_sync_togasupply.php` (~L637-673) calls `App_Api_Toga2::syncSalesOrderFromNetsuite()`
+  **bare**. `send()` throws on any non-success by default, so **one poison order throws, propagates,
+  and aborts the whole section BEFORE** the cursor PUT + `finishModeIteration()`. The mode stays
+  `1-RUNNING`, the watermark freezes, the window shrinks ÷3 each run, and the **same** order is
+  re-tried and re-throws every 5 minutes — a permanent freeze, not a skip. So a stuck
+  `SALES_ORDERS` at `1-RUNNING` with a days-frozen watermark means **it is throwing on a specific
+  order** (go read the live api2 transaction log for that client — see the poison-order gotcha
+  below). The "shrinking window is a bug signal" rule still holds; the "record is stepped over"
+  corollary does **not** for this section.
 
 Proven concretely on Elite: sales order **169441** (NetSuite internal id 4624062, trandate
 2024-04-15, customer PO `BEGGS/04152024/…`) was simply absent from `Client_Elite.SalesOrders`
@@ -361,9 +376,46 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
   a new line is actually created. Full root cause, the prod cleanup migration, and the
   deploy-fix-before-cleanup sequencing live in the
   [Compass ODP Duplicate PO-Line Cleanup](../../../clients/compass-usa/workflows/odp-duplicate-po-line-cleanup.md).
+- **⚠ A single un-deletable renumbered line could freeze the entire SALES_ORDERS section (fixed
+  2026-08-17).** When NetSuite renumbers a line, `syncSalesOrderFromNetsuite` renumbers by
+  **DELETE `/sales-order-items/{uuid}` then re-create in the per-item loop**. Its "pinned row" guard
+  only skipped rows carrying `itemFulfillmentItems` / `salesOrderItemPurchaseOrderItems` /
+  `purchaseOrderItemSalesOrderItems`; an **INVOICED** line
+  (`InvoiceItems.salesOrderItemId`, `ON DELETE RESTRICT`) was **not** guarded, so the DELETE failed
+  with MySQL **1451** → api2 **EV-11** 400, and — because the SALES_ORDERS loop has no per-record
+  `try/catch` (see the corrected gotcha above) — the throw aborted the section, freezing Compass USA
+  for ~5 days (`NETSUITE_EXECUTION_MODE_SALES_ORDERS='1-RUNNING'`, watermark stuck at
+  `2026-08-12 06:13:26`) while it re-tried the same poison order every run (SO **7447** /
+  `SalesOrderItem` 47828, invoiced by `InvoiceItem` 25515). **Fix (library-only, PHP 7.2-safe, no
+  signature changes)** in `syncSalesOrderFromNetsuite`: (1) the renumber-DELETE now passes
+  `$throwExceptionOnApiError=false`, checks `empty($resp->isSuccess)`, and records any row it cannot
+  delete in a new `$pinnedRenumberLineUniqueKeys` set (keyed by `c_netsuiteLineUniqueKey`); (2) the
+  per-item PUT loop treats a row in that set as **pinned** — it keeps its current `lineNumber` (no
+  `UNIQUE(salesOrderId,lineNumber)` collision) and its PUT is made non-throwing + `error_log` **for
+  pinned rows only** (normal rows keep throw-on-error so real failures still surface); (3) the
+  trailing "remove dropped items" DELETE now skips `invoiceItems` and checks `isSuccess`. Net: **no
+  single order can freeze the section again regardless of which `RESTRICT` child blocks a delete**;
+  the invoiced line simply stays at its existing `lineNumber` (a documented unresolvable
+  NetSuite-vs-invoiced case). Deploy `library` only — no SQL, no other repos — then the section
+  completes, mode flips IDLE, and the backlog backfills idempotently. Note the collection guard added
+  for `invoiceItems` is **best-effort only**: depth-4 `GET /sales-orders` does **not** return the
+  `itemFulfillmentItems` or `invoiceItems` reverse-hasMany collections (only the PO-link bridges), so
+  the fix keys off the recorded "could-not-delete" set rather than trusting those collections — see
+  [App_Api_Toga2 client & bridge](../../library/features/toga2-api-client-and-bridge.md).
 
 ## Change history
 
+- 2026-08-17 — Fixed a Compass USA ~5-day SALES_ORDERS freeze: an **invoiced** line that NetSuite
+  renumbered could not be DELETEd (FK `InvoiceItems.salesOrderItemId` `RESTRICT` → MySQL 1451 →
+  api2 EV-11), and because the SALES_ORDERS loop has **no per-record `try/catch`** the throw aborted
+  the whole section (mode stuck `1-RUNNING`, watermark frozen, poison order SO 7447 re-tried every
+  run). `syncSalesOrderFromNetsuite` now makes the renumber-DELETE non-throwing, records
+  un-deletable rows in a `$pinnedRenumberLineUniqueKeys` set, and keeps a pinned row at its existing
+  `lineNumber` with a non-throwing PUT (normal rows still throw on error); the trailing dropped-item
+  DELETE now skips `invoiceItems` and checks `isSuccess`. **Corrected** the prior gotcha that claimed
+  a per-record failure never stops the cursor — that is **section-specific and false for
+  SALES_ORDERS**, which has no per-record isolation. Library-only deploy; no SQL/other repos.
+  Diagnosis touched worker/api2/_underscore (read-only). (jcardinal)
 - 2026-08-12 — TRUE-80499 (Elite onboarding, shared-engine work). **Fixed** the sparse-client
   `TypeError`: the two per-client item lookups are now initialised at
   `common_sync_togasupply.php:74-75` instead of only inside the items loop, so a client whose items

package/knowledge/2.0/apps/api2/features/api-payload-interceptors.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-14
-owners: ["mhammontree", "dfranks", "bala", "snaredla"]
+updated: 2026-08-17
+owners: ["mhammontree", "dfranks", "bala", "snaredla", "jcardinal"]
 files:
   - api2/Component/Api/V2/V2.php
   - api2/Controller/Index.php
@@ -448,6 +448,13 @@ and the failing environment**. It is a small table, and the drift is usually exa
 
 ## Change history
 
+- 2026-08-17 — Corroborated that the unguarded-dispatch fatal is **systemic, not client-specific**:
+  the prod "undefined method" issue bucket (`Logs.Issue` ref 3G / id 59) grouped **both**
+  `_Model_Compass_Usa_SalesOrderItem::postPost()` **and** `_Model_Elite_SalesOrder::postPut()` — two
+  different tenants, one shared fragility. (This was the original Compass USA failure on 2026-08-12,
+  before it was mitigated on the 2.0 side and the client's NetSuite sync progressed to an unrelated
+  FK failure downstream.) Reinforces the standing fix direction: guard all four `V2.php` call sites
+  with `method_exists()`. Investigation only, no code change. (jcardinal)
 - 2026-08-14 — TRUE-80489, from building the Compass inactive-standalone-item order guard.
   (1) **A PRE interceptor on a PARENT record fires on the nested child POST, with the CHILD as the
   payload.** `POST /sales-orders/{uuid}/sales-order-items` resolves `SalesOrders` as the

package/package.json

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