toga-ai 1.0.945 → 1.0.946

package/knowledge/2.0/apps/_underscore/features/units-for-items-for-purchase-orders.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
+updated: 2026-10-05
 owners: ["bala", "tcox", "jcardinal"]
 files:
   - _underscore/Model/Client/ServiceRequest.php
@@ -21,6 +21,7 @@ related:
   - ./tracking-number-bridges.md
   - ../../../clients/elite/features/supply2-tableview-config-drift.md
   - ../../../clients/prudential/features/supply-orders-csv-export.md
+  - ../../../clients/nychh/features/transfer-order-notification-emails.md
 ---
 
 How unit (serialized inventory) data links to sales-order/purchase-order line items behind the `units-for-items-for-purchase-orders` view; open when units don't show, a unit-to-order path is needed, or a view here 500s.
@@ -131,7 +132,7 @@ Header-level vs item-level bridges, and the level each transaction is anchored a
 - **The view only walks the receipt path.** A line whose units exist solely via the fulfillment path (shipped from stock, never received against the bridged PO line) shows **0 units** even though units physically exist. No data backfill can surface these — only a resolver/view change that also walks the fulfillment path will.
 - **Missing item bridge → no units**, even when units were received. Without a `SalesOrderItems_PurchaseOrderItems` row, the receipt path has no starting link.
 - **A present bridge is not sufficient.** If the bridged PO line has no `ItemReceiptItemUnits`, the receipt path still resolves to nothing. The **fulfillment-chain** analog (NYCHH rebuild): a PO line with a bridge **and** a fulfillment but **zero `ItemFulfillmentItemUnits`** (no serialized units captured) correctly shows an **empty grid** — that is not a bug, just a line with no serials recorded.
-- **`inventoryType` determines unit existence**: `SERIALIZED` and `HYBRID` items can produce unit records; `NON_SERIALIZED` (bulk/consumable) never do. `HYBRID` items fulfilled as a plain quantity (no serial capture) also produce no units — legitimately blank.
+- **`inventoryType` determines unit existence**: `SERIALIZED` and `HYBRID` items can produce unit records; `NON_SERIALIZED` (bulk/consumable) never do. `HYBRID` items fulfilled as a plain quantity (no serial capture) also produce no units — legitimately blank. **Only `SERIALIZED` is reliable enough to *expect* units from.** `Items.inventoryType` is `enum('SERIALIZED','NON_SERIALIZED','HYBRID')` and the constants live on `_Model_Client_Item` (`INVENTORY_TYPE__SERIALIZED`) — compare against those, never a raw string. Measured on prod `Client_Nychh` fulfillment lines: NON_SERIALIZED **0 of 2,372** ever have units, HYBRID **510 of 5,743**, SERIALIZED **1,242 of 1,389**. So any "this line is missing its units/asset tags" alert must be gated on SERIALIZED or it fires on every accessory — see [NYCHH transfer-order emails](../../../clients/nychh/features/transfer-order-notification-emails.md).
 - **Receipt-path counts are PO-line-wide.** Units surfaced reflect everything received against the bridged PO line, which may exceed or differ from what was actually fulfilled to a given sales order (over/under-attribution), because attribution is by PO line, not by the fulfillment that shipped the unit.
 - **A 500 here is usually stale per-client view config, not missing data.** This view's joins were repointed onto the bridge records (319 tracking, 289 `SalesOrderItems_PurchaseOrderItems`) per client. A client that never got that migration 500s on `table-views/meta` (*"Model build for primary key id '1431' for `_Model_Core_RecordField` … 0 rows"*) and then on the data query (*"Unknown column `SalesOrderItems_PurchaseOrderItems.salesOrderItemId` in 'on clause'"*). Confirmed on `Client_Elite` (view 17) — see [Elite TableView config drift](../../../clients/elite/features/supply2-tableview-config-drift.md). Check the view config before investigating the linkage paths above.
 - **A join can also be broken by a `parentRecordFieldId` that belongs to a record the view never joins.** Distinct from the dead-id case above: the id **exists**, it is just on the wrong record. Found 2026-08-17 - a join in this view carried `parentRecordFieldId` **92**, which belongs to record **289** (`SalesOrderItemPurchaseOrderItems`), a record the view does not join anywhere, and it **500'd** the view. **Proven by bisection:** all 23 other joins returned 200; adding this one returned 500. No fields or joins depended on it, so the fix was a targeted `DELETE`. The same row is present in **Elite, Compass and Prudential**. When a view 500s and the ids all resolve, check that every `parentRecordFieldId` sits on a record the view actually joins - and bisect the joins rather than reading the SQL.
@@ -144,3 +145,6 @@ Header-level vs item-level bridges, and the level each transaction is anchored a
 - [tableview-joins](./tableview-joins.md)
 - [Elite supply2 TableView config drift](../../../clients/elite/features/supply2-tableview-config-drift.md)
 - [Prudential Sales Orders CSV export](../../../clients/prudential/features/supply-orders-csv-export.md)
+
+## Change history
+- 2026-10-05 — Tightened the `inventoryType` gotcha: named the `_Model_Client_Item::INVENTORY_TYPE__SERIALIZED` constant and added the prod NYCHH counts (NON_SERIALIZED 0 of 2,372 lines ever carry units, HYBRID 510 of 5,743, SERIALIZED 1,242 of 1,389), so a "missing units" alert is gated on SERIALIZED. (bala)

package/knowledge/2.0/apps/worker2/features/nychh-asset-tag-backfill.md

@@ -6,7 +6,7 @@ project: Worker
 client: nychh
 type: client-feature
 status: active
-updated: 2026-09-16
+updated: 2026-10-05
 owners: ["bala"]
 files:
   - worker2/Worker/Client/Nychh.php
@@ -58,6 +58,31 @@ Two 1.0 `worker` scripts (run via PuTTY) back this up:
 - **`worker/crons/toga2/netsuite/verify_fulfillment_asset_tag_sync_nychh.php`** — read-only, compares NetSuite vs TOGa per fulfillment to confirm the sync grabbed tags correctly.
 - **`worker/crons/toga2/netsuite/backfill_all_asset_tags_from_netsuite_nychh.php`** — full-history SOAP per-serial backfill; `DRY_RUN` default, never-blank, resumable via a ledger file.
 
+## ⚠ Open defects — the cron succeeds and fills 0 units
+
+Cron **`Core.CronJobs` id 44**, `0 7,16 * * *`, `{"dryRun": false}`. It **reports success** every
+run: 60,565 of 61,174 serials found, 24,978 carrying a NetSuite tag — and writes **0 units**.
+Three faults, all **open as of 2026-10-05** (found, not fixed):
+
+1. **`fetchTagsForSerials()` never paginates.** It sends 500 serials per chunk with `?limit=1000`
+   and reads `$page->items` **once**. Serials are **not unique** in NetSuite — 1,151,658
+   `inventorynumber` rows against 1,126,401 distinct values, and junk serials make it worse
+   (`'NA4'` alone returns 9 rows) — so a chunk can overflow one page and the tail is dropped
+   silently. That matches the 609 serials the run cannot find (inferred from the counts, not
+   reproduced).
+2. **`loadUnitsBySerial()` keys units by serial** (`$unitsBySerial[$serial] = $row`). Prod has
+   **61,643 units with a serial but only 61,166 distinct**, so **477 units are overwritten** in the
+   map and can never be filled, whatever NetSuite holds.
+3. **`fetchTagsForSerials()` keys the NetSuite side by serial too** — last row wins, so a row
+   with a NULL tag can **wipe a good value** read moments earlier.
+
+Live case that exposed it: units **57144** and **59631** (serials `62C26G4`, `B2C26G4`) are blank
+in `Client_Nychh.Units` since 12 Sep while NetSuite holds `ITD0081907` / `ITD0081919`.
+
+**Do not over-correct — most blank tags are legitimately blank.** A sample of 25 blank-tag
+serials had a NULL asset tag in NetSuite as well. Fixing the three faults recovers hundreds of
+units, not tens of thousands.
+
 ## Gotchas
 
 - **Do not filter on the custom columns.** SuiteQL will `SELECT` `custitemnumber_asset_tag` / `custitemnumber_mac_address` but a `WHERE custitemnumber_asset_tag IS NOT NULL` returns **0 rows with no error** — see the SuiteQL custom-field gotcha in [netsuite-rest-client](../../_underscore/features/netsuite-rest-client.md). Filter on the native `inventorynumber` column, select the custom columns, filter blanks in PHP.
@@ -70,3 +95,6 @@ Two 1.0 `worker` scripts (run via PuTTY) back this up:
 - [NetSuite ↔ TOGa Supply per-client sync](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md) — the fulfillment sync this backstops.
 - [creating-worker-actions](creating-worker-actions.md) — dispatch + `DB_CLIENT` auto-registration.
 - [NYCHH profile](../../../clients/nychh/profile.md).
+
+## Change history
+- 2026-10-05 — Recorded three open faults behind the "succeeds but fills 0 units" runs: no pagination in `fetchTagsForSerials()` (serials are not unique in NetSuite), and serial-keyed maps on both the TOGa side (477 of 61,643 units lost) and the NetSuite side (a NULL-tag row overwrites a good one). Also recorded the counter-evidence that most blank tags are genuinely blank in NetSuite. Not fixed. (bala)

package/knowledge/clients/nychh/features/transfer-order-notification-emails.md

@@ -6,7 +6,7 @@ project: Worker
 client: nychh
 type: client-feature
 status: active
-updated: 2026-10-01
+updated: 2026-10-05
 owners: ["bala", "rgirish", "jcardinal"]
 files:
   - worker2/Worker/Client/Nychh/TransferOrderEmails.php
@@ -18,6 +18,7 @@ files:
   - dbchanges2/Core/2026-09-16a - NychhTransferOrderEmailsCron.sql
 related:
   - ./transfer-order-netsuite-push.md
+  - ../../../2.0/apps/_underscore/features/units-for-items-for-purchase-orders.md
   - ./netsuite-transfer-order-import.md
   - ../../../2.0/apps/_underscore/features/email-template-sending.md
   - ../../../2.0/apps/_underscore/features/email-send-pipeline.md
@@ -157,8 +158,21 @@ PUT follows.** Fulfillment **2704** in production: header row at 20:33:09, lines
 Added 2026-09-30 (TRUE-82111). `SendFulfillment` runs `readLinesMissingAssetTags()` whenever
 **packed** is one of the stages still owed. A fulfillment line counts as **short** when either:
 
-- it has **fewer linked units than its quantity** (`unitsLinked < ItemFulfillmentItems.quantity`), or
-- a linked unit has a **blank `Units.assetTag`**.
+- the item is **`SERIALIZED`** and it has **fewer linked units than its quantity**
+  (`unitsLinked < ItemFulfillmentItems.quantity`), or
+- a linked unit has a **blank `Units.assetTag`** — that half holds whatever the item type is.
+
+**⚠ The unit-count half is SERIALIZED-only.** `Client_Nychh.Items.inventoryType` is
+`enum('SERIALIZED','NON_SERIALIZED','HYBRID')`; only SERIALIZED items are expected to carry units,
+so the query compares against `_Model_Client_Item::INVENTORY_TYPE__SERIALIZED` — never a raw
+string. Type-blind, the rule reported every accessory as missing tags: the first live exception
+(fulfillment **330197** on transfer order **291771**, 2026-10-05 09:42) fired on `AC785544`, a
+wired desktop set. Measured on prod NYCHH fulfillment lines, NON_SERIALIZED lines have **never**
+had units (0 of 2,372), HYBRID only 510 of 5,743, SERIALIZED 1,242 of 1,389 — the type-blind rule
+would have warned on roughly **7,600 normal lines**. After the fix shipped the same fulfillment
+passed at 10:10 and Order Packed went out with the accessory line correctly ignored. The
+underlying rule lives in
+[inventoryType determines unit existence](../../../2.0/apps/_underscore/features/units-for-items-for-purchase-orders.md).
 
 When any line is short, `SendFulfillment` **returns before writing
 `c_transferOrderEmailStageSent`** — so packed stays pending and the backstop cron re-sends it by
@@ -320,8 +334,10 @@ Cost of the split, stated so nobody is surprised later:
 
 ## Testing
 
-**106 tests** as of 2026-09-30. Each fix is proven by **reverting it** and confirming the matching
-tests fail. The five scenarios were then run end to end on **dev sandbox** against fulfillment
+**111 tests** as of 2026-10-05 — the last five cover the SERIALIZED-only unit-count rule, including
+a mixed fulfillment whose exception email names only the serialized line. Each fix is proven by
+**reverting it** and confirming the matching tests fail (reverting the inventory-type rule fails
+three). The five scenarios were then run end to end on **dev sandbox** against fulfillment
 **898** / transfer order **286536**.
 
 A local end-to-end harness (scratchpad, **not committed**) runs the **real** worker class against a
@@ -332,6 +348,14 @@ loaded out of the dbchanges2 file so an unresolved `{placeholder}` fails a test.
 unescaped values and both detail-box defects were all found there, not in production.
 
 ## Change history
+- 2026-10-05 — **The asset-tag hold now only counts missing units on `SERIALIZED` items**
+  (TRUE-82111). `readLinesMissingAssetTags()` treated "fewer linked units than quantity" as missing
+  tags for every item, so accessories were reported short: first prod exception was `AC785544`, a
+  wired desktop set, on fulfillment 330197 / transfer order 291771. Now compared against
+  `_Model_Client_Item::INVENTORY_TYPE__SERIALIZED`; the blank-`assetTag` half is unchanged. Prod
+  shows NON_SERIALIZED lines never carry units (0 of 2,372), so the old rule would have warned on
+  ~7,600 normal lines. Shipped and verified live: same fulfillment passed at 10:10 and Order Packed
+  sent. Harness now 111 tests. (bala)
 - 2026-10-01 — **Packed/shipped are now HELD when a fulfillment line is short of asset tags**
   (TRUE-82111). A line is short when it has fewer linked units than its quantity **or** a linked unit
   has a blank `assetTag`; `SendFulfillment` then returns without writing

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

@@ -48,6 +48,8 @@ WHERE PurchaseOrders.vendorId = 1        # Dell = Vendors.id 1
   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 selected here. Unit/bundle/SO/PO creation happens elsewhere and does **not** send anything to Dell.
 
+**⚠ The ship-to address Dell receives comes from `ServiceRequests.deliverToAddressId`, NOT the PO's `shipToAddressId`.** The cron joins `LEFT OUTER JOIN Addresses ON Addresses.id = ServiceRequests.deliverToAddressId` and sends `Addresses.line1` as `shipAddress.address1`. A separate `Addresses` row *is* created for the PurchaseOrder, and it is **not** the one transmitted. Correcting a bad Dell address means editing the **SR's deliverTo row**; fixing only the PO's address changes nothing and the same rejection repeats.
+
 ### 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 in config, not in this doc).
@@ -56,6 +58,14 @@ WHERE PurchaseOrders.vendorId = 1        # Dell = Vendors.id 1
 - **Event model (the key change):** the new schema adds a required **`requestEvent`** field — `'Create'` for new orders, `'Update'` for updates, `'Cancel'` for cancellations. Replaces the old overloaded `svcOrderType` that previously signalled both the SR type AND the event (`'CANCEL'`/`'UPDATE'`). In V2, `requestType` carries the SR type only (Refresh / Breakfix / Reclaim / Bulk).
 - **Optional pre-submission validation:** `App_Api_Delllch::validateLCHRequestV2(array $payload, bool $isProduction = true): mixed` calls `api/v2/validate/LCHRequestV2` — returns 200 on a valid payload, `422` with a `problems[]` / `issues[]` array on schema violations.
 
+### What a pre-send 422 does (and does not) do
+Order of operations in each regional cron: **validate → send → stamp**.
+1. `POST api/v2/validate/LCHRequestV2`. A rejection is `422` with e.g. `{"msg":{"problems":1,"issues":["Unsupported [shipAddress.address1] is a PO Box"]}}` — **Dell refuses PO Box ship-to addresses.**
+2. On failure the cron emails `devteam@togatech.com` + `vburks@togatech.com`, throttled to **once an hour per PO** via `PurchaseOrders.c_dtLastValidationAlert`, then `continue`s. `dtSubmitted` is left NULL "so it retries once the data is corrected".
+3. On success it POSTs `api/v2/request/LCHRequestV2` (Dell answers **202**) and only then runs `UPDATE PurchaseOrders SET dtSubmitted = NOW()` — which is what drops the PO out of the queue.
+
+**Consequence: fixing the data is enough. No manual push, no re-queue** — the next 5-minute run picks the PO up and stamps it.
+
 ### Payload schema migration (old → new)
 | Old (`LCHRequest`) | New (`LCHRequestV2`) |
 | --- | --- |
@@ -108,11 +118,13 @@ Verification plan:
   - **The country-split cutover (~2026-07-17) is when this started biting.** Before the split, `transmissions_to_dell_v1.php` had **no customer gate**, so every REQ transmitted regardless. The regional split files added `INNER JOIN Customers` + `WHERE Customers.uuid = '<region>'`, which drops NULL-`customerId` REQs. ~38 REQs stranded this way since the cutover.
   - **Remediation:** backfill `ServiceRequests.customerId = 3` (USA) for the stuck US-ship-to REQs; **durable fix** = have the generation cron derive country/`customerId` from `deliverToAddress` so `customerId` is never NULL.
 - **`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. `getAccessToken()` also does not check the token-call result (silent 401 path). Second way an order can silently fail to reach Dell; fix later by inspecting the response before stamping.
+- **⚠ A 422 retries forever — a permanent data rejection is treated as transient.** Because validation failure `continue`s without stamping `dtSubmitted`, the same PO is re-selected **every 5 minutes, indefinitely**. One PO Box address cost **748 Dell asset lookups between 2026-09-18 and 2026-09-22** (~280 calls/day), each ending in the same 422. A 422 is a schema/data rejection that will never pass on retry: it should **park** the request (stamp a failure state) rather than re-queue. Until that is built, the hourly alert email is the only stop signal — and it stops nothing.
 - `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 reproduces the old overloaded `svcOrderType` bug under the new schema.
 - Dell deprecated `LCHRequest`; any script still POSTing to the old route will fail. All four transmission scripts must point at `LCHRequestV2`.
 - The removed fields (e.g. `deviceType`, `lob`, `imageType`) will be rejected by V2 validation — do not reintroduce them.
 
 ## Change history
+- 2026-10-05 — Recorded that the Dell ship-to comes from `ServiceRequests.deliverToAddressId` (not the PO address), Dell's PO Box 422, and the forever-retry loop a 422 creates (748 lookups for one bad address). Investigation only, no code change. (bala)
 - 2026-09-29 — Noted the provision profile is read from the linked bundle; wrong bundle link sent India REQs the USA profile. (rgirish)
 
 ## Related

package/package.json

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