toga-ai 1.0.431 → 1.0.433

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

@@ -18,6 +18,7 @@
 | [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | worker2/Component/Forecast/SaleImport/SaleImport.php, worker2/Component/Forecast/Db/Db.php, _underscore/Component/Api/Netsuite/Netsuite.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/JournalEntry.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Forecast/2026-06-26a - Add journalEntry to Sales transaction type enum.sql, test/@dave/test_invoice_lifecycle.php, test/@dave/test_je_lifecycle.php, test/@dave/test_creditmemo_lifecycle.php, test/@dave/test_cashsale_lifecycle.php, test/@dave/test_cashrefund_lifecycle.php, test/@dave/test_fetchrecord_routes.php, test/@dave/verify_je_classification.php, test/@dave/probe_je_accounts.php, test/@dave/probe_je_shape.php, test/@dave/fixer.php, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/Junk Drawer/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
 | [isFulfillable Propagation Up the SO↔PO Chain](features/fulfillable-item-propagation.md) | `Items.isFulfillable` is a boolean that gates whether a storefront line's **Qty Fulfilled** cell is actionable. | _underscore/Model/Client/Item.php, _underscore/Model/Compass/Item.php, dbchanges2/Core/2026-07-17 - Items isFulfillable RecordField.sql, dbchanges2/Core/2026-07-17 - RegisterItemIsFulfillableInterceptors.sql, dbchanges2/Client/2026-07-17 - ItemsisFulfillable.sql |
 | [Item-Fulfillment Stage Lifecycle (picked/packed/shipped) & Order Status](features/item-fulfillment-stage-lifecycle-and-order-status.md) | Every ItemFulfillment (IF) now carries an explicit **stage** — picked → packed → shipped — resolved through `ItemFulfillmentStages → ItemFulfillmentStatuses` (m | _underscore/Model/Client/SalesOrder.php, _underscore/Model/Quad/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/SalesOrderStatus.php, _underscore/Model/Client/SalesOrderItem.php, _underscore/Model/Client/Item.php, _underscore/Model/Client/PurchaseOrderItem.php, library/app/api/toga2.php, dbchanges2/Client/2026-06-30a - BackfillNullStageItemFulfillmentsToShipped.sql, dbchanges2/Client/2026-06-30b - SalesOrderStatusesPickedPacked.sql, dbchanges2/Client/2026-06-30c - ItemFulfillmentStageIdNotNull.sql, dbchanges2/Client_CompassCanada/2026-06-30a - ItemFulfillmentLifecycleAndShippedBackfill.sql |
+| [DB-free unit testing for _underscore model interceptors](features/model-interceptor-unit-testing.md) | `_underscore` shipped with **no** PHPUnit setup (no `composer.json`/`phpunit`; only vendored PhpOffice tests existed). | _underscore/Test/bootstrap.php, _underscore/Test/Prudential/ServiceRequestTest.php |
 | [_Model magic-field access (__get without __isset)](features/model-magic-field-access.md) | `_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`. | _underscore/Model/Core/Model.php |
 | [_Model::save() vs raw _Query — no atomic conditional update](features/model-save-vs-query-atomic-update.md) | `_Model::save()` is a plain load-then-write ORM primitive and **cannot express an atomic conditional update** (an optimistic-concurrency / row-claim guard such | _underscore/Model.php, _underscore/Query.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php |

package/knowledge/2.0/apps/_underscore/features/model-interceptor-unit-testing.md

@@ -0,0 +1,67 @@
+---
+title: "DB-free unit testing for _underscore model interceptors"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-07-24
+owners: ["bala"]
+files:
+  - _underscore/Test/bootstrap.php
+  - _underscore/Test/Prudential/ServiceRequestTest.php
+related:
+  - ../../../../clients/prudential/features/service-request-address-validation.md
+---
+
+## Summary
+
+`_underscore` shipped with **no** PHPUnit setup (no `composer.json`/`phpunit`; only vendored
+PhpOffice tests existed). This is the first test scaffold in the repo and establishes a runnable,
+**DB-free** pattern for exercising the pure-validation logic inside a model's `prePost` /
+interceptor methods without a database or the full framework bootstrap. It was introduced with the
+Prudential `validateCustomer()` guard (see the service-request address-validation client-feature).
+
+## Key files / entry points
+
+- `_underscore/Test/bootstrap.php` — the test bootstrap. It **stubs `_Model_Client_ServiceRequest`**
+  (the DB-backed base class) and then `require`s the real `Exception/Validation.php` and the real
+  model under test, so the guard code runs unchanged with **no DB connection**.
+- `_underscore/Test/Prudential/ServiceRequestTest.php` — 6 regression tests for the private
+  `validateCustomer()` guard.
+
+## How it works
+
+1. The bootstrap defines a minimal stub for the model's DB-backed parent
+   (`_Model_Client_ServiceRequest`) so the class under test can be loaded without the ORM/DB layer.
+2. It `require`s the **real** `_Exception_Validation` and the **real** model file, so the actual
+   production validation code executes — only its persistence base is stubbed.
+3. Private validators (e.g. `validateCustomer()`) are invoked through **PHP reflection**, letting a
+   test assert on a single private method's behaviour directly instead of driving a full POST.
+4. Run it with:
+
+   ```
+   phpunit --bootstrap _underscore/Test/bootstrap.php _underscore/Test
+   ```
+
+The initial suite covers the `validateCustomer()` guard: absent `customer`, null `uuid`,
+empty-string `uuid`, whitespace-only `uuid`, error-message content, and a valid `uuid` passing.
+Verified 6/6 passing against the real code.
+
+## Gotchas / known issues
+
+- **Reflection on private methods is the pattern here** — the interceptor validators are private,
+  so tests use `ReflectionMethod::setAccessible(true)`. Keep testing them directly rather than
+  making them public just to test them.
+- **Stub only the persistence base, load the real logic.** The value of the pattern is that the
+  production validator runs unchanged; do not reimplement the validator in the stub.
+- There is still no `composer.json`/autoloader for the repo — tests rely on the explicit
+  `--bootstrap` file to wire up requires. Adding more model tests means extending
+  `Test/bootstrap.php` with the stubs that model needs.
+
+## Change history
+- 2026-07-24 — Created: first PHPUnit scaffold in `_underscore` (`Test/bootstrap.php` +
+  `Test/Prudential/ServiceRequestTest.php`), a DB-free pattern that stubs the model's persistence
+  base and reflects into private interceptor validators; seeded with 6 regression tests for the
+  Prudential `validateCustomer()` guard. (bala)

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

@@ -19,7 +19,7 @@
 | [Etilize Item Translation Import](features/etilize-item-translation-import.md) | The abstract worker class `_Worker_Etilize_ItemTranslations` imports **non-English** item text from Etilize into the client's `ItemTranslations` table. | worker2/Worker/Etilize/ItemTranslations.php |
 | [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/Monitors/RateEntitlement.php, worker2/Worker/Notification/Email.php, worker2/Worker/Rate.php, dbchanges2/Core/2026-05-21 - Monitors.sql, dbchanges2/Core/2026-06-29a - Rate Entitlement Contract Monitor.sql |
 | [NetSuite ↔ ClickUp / 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/Worker/Clickup.php, worker2/Worker/Clickup/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, test/@dave/test_model_load_behavior.php, dbchanges2/Forecast/2026-06-25a - Add unique index on Opportunities netsuiteOpportunityInternalId.sql, _underscore/Model/Forecast/Opportunity.php, test/@dave/approach/TRUE-80044.md, 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, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_open_order_gating.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, worker2/Component/Forecast/Db/Db.php, worker2/Worker/Netsuite/Location.php, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_amq_invoice_resync_salesorder.js, 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, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_open_order_gating.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite Supporting-Record Webhook Importer (the reusable recipe)](features/netsuite-supporting-record-webhook-importer.md) | A single **repeatable recipe** for porting a legacy daily-pull NetSuite *supporting-record* importer (the lookup/dimension tables behind Forecast2 — Employees, | worker2/Worker/Netsuite/Employee.php, worker2/Worker/Netsuite/Account.php, worker2/Worker/Netsuite/Classification.php, worker2/Worker/Netsuite/Customer.php, worker2/Worker/Netsuite/Item.php, worker2/Worker/Netsuite.php, _underscore/Model/Forecast/Employee.php, _underscore/Model/Forecast/Account.php, _underscore/Model/Forecast/Classification.php, _underscore/Component/Forecast/Db/Db.php, test/@dave/test_employee_lifecycle.php, test/@dave/test_account_lifecycle.php, test/@dave/test_classification_lifecycle.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, worker/crons/toga2/forecast2/import_supporting_records.php |
 | [Background Email-Template Worker (_Worker_Notification_EmailTemplate)](features/notification-email-template.md) | `_Worker_Notification_EmailTemplate::Send(...)` dispatches a **stored, client-defined `EmailTemplates` row off-thread** as a background WorkerJob. | worker2/Worker/Notification/EmailTemplate.php, worker2/Worker/Client/True.php, _underscore/Model/Client/EmailTemplate.php |
 | [DB-Driven Notification (Internal) Email](features/notification-email.md) | Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated, not client-facing transactional mail) are sent through one worker | worker2/Worker/Notification/Email.php, _underscore/Model/Client/EmailTemplate.php, dbchanges2/Client/2026-06-23a - EmailTemplateWrapper.sql, dbchanges2/Client_True/2026-06-23a - EmailTemplateWrapper.sql |

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

@@ -6,11 +6,15 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-29
+updated: 2026-07-24
 owners: ["dfranks"]
 files:
   - worker2/Worker/Netsuite/SalesOrder.php
   - worker2/Worker/Netsuite.php
+  - worker2/Component/Forecast/Db/Db.php
+  - worker2/Worker/Netsuite/Location.php
+  - test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js
+  - test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_amq_invoice_resync_salesorder.js
   - test/@dave/probe_salesorder_rest_shape.php
   - test/@dave/probe_open_order_lines.php
   - test/@dave/check_so_status.php
@@ -127,32 +131,105 @@ The table lives in the **`Forecast` schema on the core2 cluster** (reader
 sales-order FK column is **`netsuiteSalesOrderInternalId`** (`int unsigned`) — note this is *not* the
 same column name used by `Forecast.Sales` (see the column-name gotcha below).
 
-### Model/DB drift to know before backfilling location / backorder / amountDue (TRUE-79162)
+### Backfilling location / backorder / amountDue onto open orders (TRUE-79162 / TRUE-80262)
 
-A planned backfill of **location, backorder, and amount-due** data onto open orders runs into three
-schema/model facts (all verified against the prod core2 reader; nothing built yet):
+A backfill of **location, backorder, and amount-due** data onto open orders runs into model/schema
+facts plus NetSuite field realities (all verified against the prod core2 reader + live NetSuite;
+planning/investigation — see change history for what is built vs. planned):
 
 - **`_Model_Forecast_OpenOrderItem` (`_underscore/Model/Forecast/OpenOrderItem.php`) does NOT declare
   `locationId` or `quantityBackordered` — even though both columns already exist in the prod
   `Forecast.OpenOrderItems` table** (`locationId` `int unsigned NULL`, `quantityBackordered`
-  `decimal(15,4) NULL`). The model declares only `id, netsuiteSalesOrderInternalId, dateOrder,
-  orderNumber, customerId, salesRepEmployeeId, classificationId, accountId, itemId, lineNumber,
-  revenue, profit`. **Writing those two fields through the 2.0 importer requires adding the
-  properties to the model first** — the column existing in the DB is not sufficient.
-- **`Forecast.Locations` is EMPTY in prod (0 rows).** Schema: `id, name, netsuiteInternalLocationId`
-  (UNIQUE, nullable), `typeId` — **no parent/hierarchy column.** Any open-order `locationId`
-  resolution returns NULL until this table is populated from NetSuite, so **populating `Locations` is
-  a hard prerequisite** for the location backfill. NetSuite returns a **leaf sub-location** but the
-  warehouse dashboard wants the **top-level location**, so a leaf→root rollup is needed (and there is
-  no parent column on `Locations` today to express it).
-- **`Forecast.OpenOrderItems` has NO `amountDue` column** (neither does `Forecast.Sales` in prod —
-  see the [Sales import doc](../../_underscore/features/forecast-sale-import.md)), and `amountDue`
-  appears in no worker2 Netsuite handler or `_Model_Forecast_*`. Importing open-order amountDue
-  needs a **new column + model field**. The amountDue source semantics from the prior Sales work
-  (TRUE-78923) — REST `amountRemaining` / SuiteQL `foreignamountunpaid`, **anchor-line only, store
-  RAW POSITIVE** — carry over, **but `amountRemaining` is an AR/invoice field**, so for an *unbilled*
-  sales order it may return null/0. **Live-probe an open SO before finalizing** the open-order
-  amountDue source.
+  `decimal(15,4) NULL`). **Writing those two fields through the 2.0 importer requires adding the
+  properties to the model first** — the column existing in the DB is not sufficient. (And per the
+  change-detection gotcha above, wire any new column into **both** `buildOpenLineRows()` and the
+  `syncOpenLines()` diff.)
+- **`Forecast.OpenOrderItems` has NO `amountDue` column** — importing open-order amountDue needs a
+  **new column + model field**.
+
+#### Why `locationId` is NULL — a missing dimension sync, not an importer bug
+
+`Forecast.Locations` is empty/underpopulated in prod, and **`resolveLocationId`
+(`worker2/Component/Forecast/Db/Db.php`) returns NULL on a miss with NO self-heal** — unlike the item
+path, which calls `_Worker_Netsuite_Item::syncItem` on a miss. `resolveLocationId` walks the leaf
+location → root via `netsuiteParentLocationId` up to the top-level warehouse (NetSuite hands back a
+**leaf sub-location** but the dashboard wants the **top-level** one).
+
+`Forecast.Locations` is populated **only** by the action `Netsuite/Location/SyncAll`
+(`_Worker_Netsuite_Location::SyncAll`, `worker2/Worker/Netsuite/Location.php`) — a full SuiteQL
+re-pull of `id/name/parent`, **upsert-only, never deletes**. There is **no per-record location
+webhook** (`location` is absent from the AMQ enqueuer `RECORD_TYPE_MAP`) and **no cron**. So if
+`SyncAll` never runs, `Locations` stays empty and **every `locationId` resolves NULL** — the
+"warehouse data missing" class of bug is a missing dimension sync, not the SO importer.
+
+**Recommended durable design:** on a `resolveLocationId` miss, call `SyncAll` **once per process**
+(the whole small dimension re-pulls in ~0.9s; a surgical single-row fetch is *worse* because you'd
+have to walk/fetch the entire parent chain anyway). Optionally add per-record location webhook
+methods `post()`/`put()` → `SyncAll`, and `delete()` → **no-op** (deleting the row would orphan
+`OpenOrderItems.locationId`). To populate prod now, enqueue `Netsuite/Location/SyncAll` manually (see
+the [architecture doc](../architecture.md) WorkerJobs pending path: INSERT a `jobType='ACTION'` row
+with `dtQueued` NULL and the JobScheduler Lambda queues it within a minute).
+
+#### amountDue on an open SO — the AR field lives on the invoice, not the sales order
+
+The amountDue semantics from the prior Sales work (TRUE-78923) do **not** transfer directly: **a
+NetSuite Sales Order REST record has NO amount-remaining / AR field.** A GET of
+`record/v1/salesOrder` returns only `subtotal`/`total`/`totalCostEstimate`; `$salesOrder->amountRemaining`
+**does not exist** and yields NULL — this is the root cause of the empty amountDue column. AR lives
+**only on the invoice**: SuiteQL `transaction.foreignamountunpaid` (equivalently REST invoice
+`amountRemaining` / `amountRemainingTotalBox`). `foreignamountunpaid` is already
+invoice-amount-less-payments (it nets applied payments **and** applied credit memos) and is NULL/0 on
+Paid-In-Full and on cash sales/refunds → wrap `NVL(...,0)`.
+
+**Compute an open SO's outstanding AR by aggregating its linked invoices (reusable SuiteQL pattern):**
+
+1. SO→invoice linkage is `previoustransactionlinelink`: `previousdoc=<soId>`, `previoustype='SalesOrd'`,
+   `nexttype='CustInvc'` → collect **DISTINCT** `nextdoc` = invoice ids. There are **multiple link
+   rows per (SO,invoice)** (`linktype` ShipRcpt/OrdBill/OrdRvCom) — you **MUST dedup on `nextdoc`** or
+   the AR triples.
+2. `SUM(NVL(transaction.foreignamountunpaid,0))` over those invoice ids.
+3. **Run PER-SO with small `IN`-lists** — the full-book JOIN+GROUP BY over all SOs returns a NetSuite
+   **400** (the framework renders an HTML error page).
+4. **TOGA SuiteQL convention: NO table aliases** — fully-qualify (`previoustransactionlinelink.nextdoc`,
+   `transaction.foreignamountunpaid`). Verified live penny-exact (26 invoices → openAr $79,448.78).
+5. **Gotcha:** NetSuite **lowercases the SuiteQL output alias** (request `openAr` → response key
+   `openar`) — read the result key case-insensitively.
+
+**Customer Deposit unapplied balance has NO direct field either — derive it.** `CustDep` records
+expose no remaining/unapplied scalar (`foreignamountunpaid` is NULL on deposits; REST
+`customerDeposit` has no remaining field) — only `foreigntotal` and `status` ("Deposited" = has
+remaining vs "Fully Applied"). Derive: `unapplied = customerDeposit.foreigntotal − SUM(the deposit's
+DepAppl application amounts)`, where the applications are `previoustransactionlinelink`
+`previousdoc=<depId>`, `previoustype='CustDep'`, `nexttype='DepAppl'` → each `DepAppl.foreigntotal`;
+the deposit reaches its SO via the `OrdDep` link (SalesOrd→CustDep). Verified: 79176 − 26392 = 52784.
+
+#### Freshness — balance events don't reach the SO's webhook; bridge via an invoice UE
+
+A 180-day audit of `Core.WorkerJobs` (`action LIKE 'Netsuite/%'`) shows which record types the AMQ
+enqueuer actually POSTs to `webhook.togahub.com/netsuite`: **SalesOrder, Invoice, Opportunity,
+JournalEntry, CashSale, CreditMemo** (+ item/customer/employee dims). It does **NOT** send
+`customerPayment`, `customerDeposit`, `customerRefund`, or `cashRefund` (all 0 in 180d) — and
+`location` is not in the map. Compounding it: **billing an SO fires no SalesOrder UE** (the saved
+record is the Invoice; submit events don't chain), and **applying a customer payment submits neither
+the invoice nor the SO** — so no balance event reaches the SO's enqueuer. Any SO-derived AR value
+therefore goes stale on billing/payment.
+
+**Bridge pattern** (`test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_amq_invoice_resync_salesorder.js`):
+a UE **on the Invoice** resolves the invoice's `createdfrom` (its parent SO — confirmed via SuiteQL
+`type='SalesOrd'`) and enqueues a `salesOrder` **'edit'** webhook → worker2 router →
+`_Worker_Netsuite_SalesOrder::importOpenOrder` re-reads and re-syncs. **To keep any SO-derived value
+fresh across balance events, route those events to a `salesOrder` edit** rather than adding new
+per-type handlers. (This is also the concrete form of the "fix direction" in the billing-not-removed
+gotcha below.)
+
+#### Backfilling recomputed columns — delete-and-reconcile beats a backfill script
+
+The Forecast reconciler's fingerprint detects record-set drift (n / idsum). **Deleting a whole SO's
+`OpenOrderItems` rows IS that drift** → the SO classifies `nsOnly` → the fixer re-fetches the SO and
+`importOpenOrder` recreates the rows **with the recomputed columns**. So no presence-check or backfill
+script is needed — delete in small batches (a brief gap until recreated). This depends on the recompute
+code being deployed and the reconciler's OpenOrders category being live; the fallback is a **per-SO
+`salesOrder`-edit webhook** (proven to recreate rows *and* resolve `locationId`).
 
 ## Client variations
 
@@ -180,7 +257,9 @@ None — uniform (platform-wide Forecast2 sync).
   silent **false-negative "order missing"** reading. Verify the schema before concluding an order is
   absent from Forecast.
 - **A successful `WorkerJobs` row does NOT prove rows were written — two silent zero-write paths.** An
-  `isSuccess=1` / `failureReason = NULL` job is **not** evidence that any `OpenOrderItems` rows persisted.
+  `isSuccess=1` job is **not** evidence that any `OpenOrderItems` rows persisted. (NB: prod
+  `Core.WorkerJobs` has **no `failureReason` column** — it was renamed to `output`, which holds both
+  failure text and success result; see the [architecture doc](../architecture.md).)
   `importOpenOrder` has two success-with-zero-write paths:
   - **(a) STATUS GATE** — if NetSuite `status->refName` is not in `OPEN_STATUSES` (`Pending Fulfillment`,
     `Partially Fulfilled`, `Pending Billing/Partially Fulfilled`, `Pending Billing`) or is missing, it
@@ -336,6 +415,24 @@ test fixture (it surfaced the stale SO 7181316 above).
 
 ## Change history
 
+- 2026-07-24 — **Resolved the open questions on the OpenOrderItems location / amountDue Power-BI
+  backfill (investigation + planning).** `locationId` is NULL because `Forecast.Locations` is
+  unpopulated and `resolveLocationId` (`worker2/Component/Forecast/Db/Db.php`) has no self-heal on a
+  miss; the dimension is filled **only** by `Netsuite/Location/SyncAll`, which has no location webhook
+  (absent from the AMQ `RECORD_TYPE_MAP`) and no cron — recommended a per-process `SyncAll` self-heal
+  (optionally a location webhook → SyncAll; delete → no-op). Root-caused the empty amountDue: **a
+  NetSuite SO REST record has no amount-remaining/AR field** (only the invoice does —
+  `transaction.foreignamountunpaid`); documented the reusable **per-SO SuiteQL AR rollup** over linked
+  invoices (`previoustransactionlinelink` `SalesOrd→CustInvc`, DISTINCT `nextdoc` or AR triples;
+  per-SO IN-lists — full-book JOIN 400s; no table aliases; NetSuite lowercases the output alias) and
+  the **Customer Deposit unapplied** derivation (`foreigntotal − Σ DepAppl`). Audited the AMQ
+  enqueuer's actual record types (180d WorkerJobs: SalesOrder/Invoice/Opportunity/JournalEntry/
+  CashSale/CreditMemo; NOT customerPayment/Deposit/Refund/cashRefund; not location) and recorded the
+  **invoice-UE → `createdfrom` → salesOrder-edit bridge** (`ue_amq_invoice_resync_salesorder.js`) as
+  the freshness fix for balance events that never reach the SO's webhook. Added the
+  **delete-and-reconcile backfill technique** (deleting an SO's OOI rows is reconciler drift → fixer
+  recreates them with the recomputed columns; no backfill script). Corrected the stale
+  `failureReason` reference (column renamed to `output`). (dfranks)
 - 2026-06-29 — **Recorded the model/DB drift + prerequisites for the open-order location/backorder/
   amountDue backfill (TRUE-79162, planning only — no code written).** `_Model_Forecast_OpenOrderItem`
   declares neither `locationId` nor `quantityBackordered` though both columns already exist in prod

package/knowledge/INDEX.md

@@ -17,9 +17,9 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 37 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 38 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 31 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 14 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 16 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)

package/knowledge/clients/prudential/INDEX.md

@@ -3,9 +3,9 @@
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
 | [Prudential: Dell ASN units PRE/POST interceptor (legacy key + flat tracking)](features/dell-asn-units-interceptor.md) | 2.0 | After the tracking-number bridge migration, the ASN unit route was renamed (`advance-shipping-notice-units` → `advance-shipping-notice-item-units`), so the inhe | _underscore/Model/Prudential/AdvanceShippingNotice.php, dbchanges2/Client_Prudential/2026-06-10 - AsnUnitsInterceptor.sql |
-| [Prudential: Dell LCH IOP transmissions (LCHRequestV2)](features/dell-lch-iop-transmissions.md) | 1.0 | Outbound order transmissions from the 1.0 worker tier to Dell's Lifecycle Hub (LCH) ITSM integration. | library/app/api/delllch.php, worker/crons/toga2/prudential/transmissions_to_dell.php, worker/crons/toga2/prudential_beta/transmissions_to_dell_india.php, worker/crons/toga2/prudential_beta/transmissions_to_dell_ireland.php, worker/crons/toga2/prudential_beta/transmissions_to_dell_usa.php |
+| [Prudential: Dell LCH IOP transmissions (LCHRequestV2)](features/dell-lch-iop-transmissions.md) | 1.0 | Outbound order transmissions from the 1.0 worker tier to Dell's Lifecycle Hub (LCH) ITSM integration. | library/app/api/delllch.php, library/app/apitransaction.php, worker/crons/toga2/prudential/transmissions_to_dell_usa.php, worker/crons/toga2/prudential/transmissions_to_dell_ireland.php, worker/crons/toga2/prudential/transmissions_to_dell_india.php |
 | [Prudential: Device information import + unit→contact linking (import_device_information.php)](features/device-information-import-and-contact-linking.md) | 1.0 | Prudential's **device-sync** cron (`worker/crons/toga2/prudential/import_device_information.php`) pulls device/asset records (from ServiceNow / the Dell CMDB fe | worker/crons/toga2/prudential/import_device_information.php, worker/crons/toga2/prudential/backfill_unit_contacts.php, dbchanges2/Client_Prudential/2026-07-07 - Contact Dedup Merge.sql |
-| [Prudential: Service Request Regional Address Validation](features/service-request-address-validation.md) | 2.0 | The `prePost` interceptor on `_Model_Prudential_ServiceRequest` validates `deliverToAddress` fields differently depending on which Prudential regional customer | _underscore/Model/Prudential/ServiceRequest.php |
+| [Prudential: Service Request Regional Address Validation](features/service-request-address-validation.md) | 2.0 | The `prePost` interceptor on `_Model_Prudential_ServiceRequest` validates `deliverToAddress` fields differently depending on which Prudential regional customer | _underscore/Model/Prudential/ServiceRequest.php, _underscore/Test/Prudential/ServiceRequestTest.php |
 | [Prudential Order Shipped Email — transmit_ordershipped_updates_prudential.php](features/transmit-ordershipped-email.md) | 1.0 | Cron script that transmits "Order Shipped" updates to ServiceNow (RITM) and sends a shipped notification email to the end user. | worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php, worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php, worker/crons/toga2/prudential/transmit_rejected_cancelled_updates_prudential.php, worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php, worker/crons/toga2/prudential_beta/generate_sales_and_purchase_orders_from_service_requests.php, worker/crons/notifications/reports/prudential_exception_report.php |
 | [Prudential Financial](profile.md) | 2.0 | Prudential is a TOGA client whose device-fulfillment flow is driven by **Dell** via the Dell API (`Client_Prudential.Apis.id = 2`). |  |
 | [Prudential: Dell ASN failed POST backfill replay](workflows/dell-asn-backfill-replay.md) | 2.0 | When Dell ASN POSTs fail in bulk (e.g. |  |

package/knowledge/clients/prudential/features/dell-lch-iop-transmissions.md

@@ -6,14 +6,14 @@ project: Worker
 client: prudential
 type: client-feature
 status: active
-updated: 2026-06-30
-owners: ["rgirish"]
+updated: 2026-07-24
+owners: ["rgirish", "bala"]
 files:
   - library/app/api/delllch.php
-  - worker/crons/toga2/prudential/transmissions_to_dell.php
-  - worker/crons/toga2/prudential_beta/transmissions_to_dell_india.php
-  - worker/crons/toga2/prudential_beta/transmissions_to_dell_ireland.php
-  - worker/crons/toga2/prudential_beta/transmissions_to_dell_usa.php
+  - library/app/apitransaction.php
+  - worker/crons/toga2/prudential/transmissions_to_dell_usa.php
+  - worker/crons/toga2/prudential/transmissions_to_dell_ireland.php
+  - worker/crons/toga2/prudential/transmissions_to_dell_india.php
 related:
   - ../profile.md
   - dell-asn-units-interceptor.md
@@ -31,6 +31,68 @@ only the request route and payload schema changed.
 This is the **outbound** counterpart to the 2.0 inbound Dell ASN flow (see
 `dell-asn-units-interceptor.md`).
 
+## Which cron is live (READ THIS FIRST)
+
+The current **production** Dell transmitters are the three regional split files in
+`worker/crons/toga2/prudential/`: `transmissions_to_dell_usa.php`,
+`transmissions_to_dell_ireland.php`, `transmissions_to_dell_india.php`. They are active in
+`worker/schedules/cron.worker.sync.json`, run every 5 minutes, and are each scoped to one
+region by `Customers.uuid`. Only the split files have the pre-send `validateLCHRequestV2`
+step and Apple-device handling.
+
+- The 119 KB monolith `transmissions_to_dell.php` is **DISABLED** — do not debug or edit it.
+- `transmissions_to_dell_v1.php` is a **dead backup** — ignore it.
+- The regional files were formerly under `crons/toga2/prudential_beta/`; they have since been
+  promoted to `crons/toga2/prudential/` and are the live production crons.
+
+## Selection query (how a REQ becomes a Dell send)
+
+Each regional cron selects Dell POs that have not yet been transmitted:
+
+```
+INNER JOIN Customers ON Customers.id = ServiceRequests.customerId
+WHERE PurchaseOrders.vendorId = 1        # Dell = Vendors.id 1
+  AND PurchaseOrders.dtSubmitted IS NULL
+  AND Customers.uuid = '<region-uuid>'
+```
+
+- **Region lives on `ServiceRequests.customerId`**, resolved through the join to
+  `Client_Prudential.Customers`. Region rows: **USA = id 3, uuid
+  `b3f7a2c1-4e89-4d6a-9c3b-8f1e5d2a7b04`**; India and Ireland are separate `Customers` rows /
+  uuids. This is NOT the SalesOrder customer — the SO customer is always
+  **"Agilant - Tech Hub" (id 1, uuid `36da53f8-38d2-404f-becf-f58f33c215d3`)**.
+- A REQ is only ever transmitted, validated, or marked once it is selected here. Unit/bundle/SO/PO
+  creation happens elsewhere and does **not** send anything to Dell.
+
+## Send mechanism
+
+- `App_Api_Delllch::send` (`library/app/api/delllch.php`) POSTs to route
+  `api/v2/request/LCHRequestV2`. Prod host `https://cms-iop.us.dell.com/iopv2/`; non-prod
+  `.../iopv2np/`.
+- Auth: OAuth2 client-credentials Bearer token obtained via `auth/token` (credentials stored in
+  config, not in this doc).
+- The split files first call `validateLCHRequestV2` (route `api/v2/validate/LCHRequestV2`) before
+  the real submit.
+
+## Transaction log (where to pull any Dell send for an audit/RCA)
+
+Dell's requested transaction record (date/time, payload, response code, response body) lives in
+`Logs_Prudential.Api`:
+
+| Column | Meaning |
+| --- | --- |
+| `dtStamp` | timestamp (indexed) |
+| `direction` | `'OUT'` for our sends to Dell |
+| `method` / `hostname` / `route` | HTTP verb, `https://cms-iop.us.dell.com`, e.g. `.../request/LCHRequestV2` |
+| `requestPayload` / `responseCode` / `responsePayload` | outbound body, HTTP status, Dell response body |
+
+Reading it:
+- A row with a `requestPayload` but **NULL `responseCode`** = curl never got an answer.
+- A `/validate/` row with **no** matching `/request/` row = validated but never submitted.
+- **Do not `LIKE`-scan on `requestPayload`** — `Logs_Prudential.Api` is millions of rows and the
+  payload is not indexed, so a `requestPayload LIKE '%REQ%'` query times out. Filter by `dtStamp`
+  (indexed) + `direction` + exact `route` instead.
+
 ## How it works
 
 - **Route:** `api/v2/request/LCHRequest` → **`api/v2/request/LCHRequestV2`** in all four
@@ -101,6 +163,23 @@ This is the established pattern for all Prudential script changes.
 3. After beta passes a full order cycle (New → shipped), confirm the production script is live.
 
 ## Gotchas
+- **NULL `ServiceRequests.customerId` = order silently never reaches Dell.** The selection
+  query's `INNER JOIN Customers ON Customers.id = ServiceRequests.customerId` drops any REQ whose
+  `customerId` is NULL, so it is never selected, never validated, never POSTed — and the Dell PO's
+  `dtSubmitted` stays NULL forever (not sent, not marked, invisible). This is the sole
+  differentiator behind "Dell has no trace of the REQ though Talos says we sent it": SO/PO/unit
+  creation all succeeded, only transmission was skipped. At one investigation 79 Dell POs were
+  stuck this way, all with `customerId` NULL. The 2.0-side guard added in
+  `service-request-address-validation.md` stops NEW customer-less REQs; already-stuck ones need a
+  `customerId` backfill from ship-to country.
+- **`dtSubmitted` is stamped without inspecting the response (latent bug, not yet fixed).** Every
+  regional cron sets `PurchaseOrders.dtSubmitted = NOW()` immediately after the send without
+  checking Dell's HTTP status, and `App_ApiTransaction::execute()` (`library/app/apitransaction.php`)
+  only throws on curl transport failure / empty / non-JSON body — **not** on HTTP >= 400. So a Dell
+  4xx/5xx rejection is recorded as "sent", the PO drops out of the `dtSubmitted IS NULL` queue, and
+  is never retried — it looks sent internally while Dell never accepted it. `getAccessToken()` also
+  does not check the token-call result (silent 401 path). This is a second way an order can silently
+  fail to reach Dell; fix later by inspecting the response before stamping.
 - `requestType` is the SR type only (Refresh/Breakfix/Reclaim/Bulk) — do **not** put the event
   there. Event signalling moved to the separate required `requestEvent` field
   (Create/Update/Cancel). Conflating them is the easiest way to reproduce the old overloaded
@@ -111,6 +190,12 @@ This is the established pattern for all Prudential script changes.
   do not reintroduce them.
 
 ## Change history
+- 2026-07-24 — Documented the live-cron reality (production is the three regional split files under
+  `crons/toga2/prudential/`; monolith `transmissions_to_dell.php` disabled, `_v1` dead), the
+  selection query, region model on `ServiceRequests.customerId` (USA id 3), the `App_Api_Delllch`
+  send route/host/auth, and the `Logs_Prudential.Api` transaction-log location + safe-query rule.
+  Recorded two silent-failure gotchas: NULL `customerId` excluded by the inner join (root cause of
+  79 stuck Dell POs) and `dtSubmitted` stamped without response inspection (latent bug). (bala)
 - 2026-06-30 — Migrated all Prudential Dell transmissions (3 beta regional + production) and
   `App_Api_Delllch` from deprecated `LCHRequest` to `LCHRequestV2` per Dell's May 2025 IOP
   spec: re-shaped payload (employee/ship/return objects, renamed return-item keys), new

package/knowledge/clients/prudential/features/service-request-address-validation.md

@@ -6,13 +6,16 @@ project: _Underscore
 client: prudential
 type: client-feature
 status: active
-updated: 2026-06-16
-owners: ["rgirish"]
+updated: 2026-07-24
+owners: ["rgirish", "bala"]
 files:
   - _underscore/Model/Prudential/ServiceRequest.php
+  - _underscore/Test/Prudential/ServiceRequestTest.php
 related:
   - clients/prudential/profile.md
   - clients/prudential/features/dell-asn-units-interceptor.md
+  - clients/prudential/features/dell-lch-iop-transmissions.md
+  - ../../../2.0/apps/_underscore/features/model-interceptor-unit-testing.md
 ---
 
 ## Summary
@@ -27,12 +30,20 @@ back to USA rules.
 ## Key files / entry points
 
 - `_underscore/Model/Prudential/ServiceRequest.php` — `prePost` interceptor; private methods
-  `resolveRegion()`, `validateUsaAddress()`, `validateIndiaAddress()`, `validateIrelandAddress()`
+  `validateCustomer()`, `resolveRegion()`, `validateUsaAddress()`, `validateIndiaAddress()`,
+  `validateIrelandAddress()`
 
 ## How it works
 
 1. `prePost` fires before each POST to `/v2/service-requests` for the Prudential client.
-2. `resolveRegion()` reads `payload->customer->uuid`, escapes it, and queries
+2. **`validateCustomer()` is the first check** (before `deliverToAddress` / region resolution). It
+   rejects the create when `customer.uuid` is missing/null/blank — the test is
+   `trim($payload->customer->uuid ?? '') === ''` — by throwing `_Exception_Validation`, which
+   `Controller/Index.php` maps to **HTTP 400**. This stops customer-less / unroutable REQs at the
+   API boundary. A customer-less REQ that slips through is exactly what strands an order: with a
+   NULL `ServiceRequests.customerId` it is silently excluded from every regional Dell
+   transmission cron (see `dell-lch-iop-transmissions.md`).
+3. `resolveRegion()` reads `payload->customer->uuid`, escapes it, and queries
    `Client_Prudential.Customers` for the matching `name`. Returns `'India'`, `'Ireland'`, or
    `'USA'` (default for anything unrecognised or when uuid is null).
 3. A `match` expression dispatches to the correct validator.
@@ -82,9 +93,12 @@ with a space (e.g. `F92 FP83`). No numeric restriction.
 
 ## Gotchas / known issues
 
-- **Null UUID = USA fallback.** All requests sent before Prudential added `customer.uuid` to
-  their payload lacked the field entirely; those are treated as USA and pass through unchanged.
-  This is intentional backward compatibility.
+- **Null/blank UUID is now REJECTED (changed 2026-07-24).** Previously a missing `customer.uuid`
+  silently fell through `resolveRegion()` to the USA default — which is how customer-less,
+  unroutable REQs (NULL `ServiceRequests.customerId`) got created and then silently dropped by the
+  Dell crons. The new `validateCustomer()` guard rejects a blank uuid with a 400, so region
+  fallback to USA now only ever applies to a uuid that is *present but unrecognised*. Already-stuck
+  REQs created before this guard still need a `customerId` backfill from ship-to country.
 - **Region check is by `Customers.name` string, not by id.** If the customer name is ever
   changed in the DB (e.g. `'USA'` → `'United States'`), the validator will silently fall
   back to USA rules for all regions. The match arms are `'India'` and `'Ireland'` only;
@@ -97,5 +111,10 @@ with a space (e.g. `F92 FP83`). No numeric restriction.
   their Dell spec). If Dell starts sending it for USA/Ireland it is silently ignored.
 
 ## Change history
+- 2026-07-24 — Added `validateCustomer()` as the first check in `prePost`: rejects a create when
+  `customer.uuid` is missing/null/blank (`trim(... ?? '') === ''`) via `_Exception_Validation`
+  (→ HTTP 400), stopping customer-less/unroutable REQs at the boundary. Previously a blank uuid
+  silently defaulted to USA, producing NULL-`customerId` REQs that the Dell transmission crons
+  drop. Backed by 6 regression tests in `_underscore/Test/Prudential/ServiceRequestTest.php`. (bala)
 - 2026-06-16 — Created: regional address validation (USA/India/Ireland) replacing the single
   USA-only `validateDeliverToAddress` method; region resolved from `customer.uuid` lookup (rgirish)

package/package.json

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