toga-ai 1.0.835 → 1.0.836

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-09-15
+updated: 2026-09-17
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -24,6 +24,7 @@ files:
   - dbchanges2/Client/2026-09-02b - NetsuiteSyncCursorRename.sql
   - test/@srija/Elite Testing/Service Requests/test_sync_togasupply_elite_section.php
   - test/@srija/Elite Testing/Service Requests/test_diagnose_togasupply_elite.php
+  - dbchanges2/_modules/netsuite/2026-09-17a - StaleSalesOrderRetirementAcl.sql
 related:
   - ../architecture.md
   - ../../../2.0/apps/_underscore/features/shipping-carriers-and-accounts.md
@@ -34,6 +35,8 @@ related:
   - ../../../clients/elite/features/netsuite-togasupply-sync.md
   - ../../library/features/netsuite-item-class-sync.md
   - ../../../clients/compass-usa/features/sales-order-line-renumbering.md
+  - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
+  - ../../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md
 ---
 
 ## Summary
@@ -711,6 +714,123 @@ nested count:
   line the fulfillment referenced, the match failed, and the section fail-loud-froze. The flat list
   replaces the truncated nested one before match/reconstruct.
 
+### Retiring the stale SalesOrder a reclassified TransferOrder leaves behind (2026-09-17, NOT YET DEPLOYED)
+
+**Turning transfer-order detection on for an existing client strands every order it already
+imported as a SalesOrder.** The same NetSuite order now syncs to a `TransferOrder`, but the old
+`SalesOrder` is never cleaned up. Its lines still carry fulfillments, so inventory **double-counts**
+and `Items._qtyOnHand` goes negative. Measured on Elite: **218** SalesOrders duplicate a
+TransferOrder on `c_netsuiteInternalSalesOrderId`, and **217 of 217** matched pairs are identical on
+order number, line count *and* total quantity.
+
+`App_Api_Toga2::retireStaleSalesOrderForTransferOrder()` (new, `private static`) is called at the
+**END** of `syncTransferOrderFromNetsuite()` so the TO and its lines exist first. Per SO line:
+
+1. move `ItemFulfillmentItems`: `salesOrderItemId` → `transferOrderItemId`,
+2. move `PurchaseOrderItems_SalesOrderItems` → `PurchaseOrderItems_TransferOrderItems`,
+3. `DELETE` the `SalesOrderItem`;
+
+then move `SalesOrders_PurchaseOrders` → `PurchaseOrders_TransferOrders` and `DELETE` the
+`SalesOrder`. **Move before delete, always** — the bridge FKs are `RESTRICT`.
+
+**The two fulfillment-parent columns are mutually exclusive, which is what makes the move safe.**
+Prod check: 391 rows TO-side, 293 SO-side, **0 with both, 0 with neither**.
+
+**It throws — never skips — on:** more than one SalesOrder for the NetSuite id; a TO with no
+lines; an SO line with no matching TO line; a line carrying `InvoiceItems` (**`InvoiceItems` has no
+`transferOrderItemId`**, so they physically cannot be moved); or any bridge whose existence check
+returns no `totalRecordCount` (see the ACL shape below). Consistent with the 2026-08-27 fail-loud
+policy.
+
+**Bridge direction is PO-FIRST, confirmed from NYCHH data rather than guessed.** The naming rule is
+`<source>_<created from it>`. `Client_Nychh` populates `PurchaseOrderItems_TransferOrderItems` (98
+rows) and `PurchaseOrders_TransferOrders` (45); the TO-first siblings are **0 in every client**. Same
+rule as the [SO↔PO bridge direction doc](../../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md).
+
+**⚠ It needs the three-layer ACL grant first.** Without `AclFieldPermissions` on records 29/325/329
+the bridge existence checks return **200 + `WZ-1` with no `meta.totalRecordCount`** and the method
+throws while blaming record ACL — the exact trap documented on the
+[ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md). The
+fleet-wide grant is `dbchanges2/_modules/netsuite/2026-09-17a - StaleSalesOrderRetirementAcl.sql`.
+
+**Open, carried forward:**
+- Elite SalesOrder **240734** has 4 `InvoiceItems` and **will throw** on retirement. Deliberate
+  fail-loud; it blocks the backfill until resolved by hand.
+- **11 of the 218** stale SalesOrders have no matching TransferOrder (4 are TOGa-created `SA1000xx`
+  with no NetSuite id). Manual review.
+- `getTransferOrderItemsByUuid()` (`toga2.php` ~L4555) has **no pagination** — it caps at
+  `recordsPerPage` 1000, unlike its paginated sibling `getSalesOrderItemsBySalesOrderUuid()`. It is
+  load-bearing for this method's safety. Skipped for now because Elite TOs are 1–5 lines; flagged by
+  php-reviewer.
+
+### ⚠ TWO code paths create `PurchaseOrderItems` — only one stamped `fulfillmentType` (fixed 2026-09-17)
+
+`fulfillmentType` was stamped by `syncPurchaseOrderFromNetsuite()` (from the order-level
+`isDropShipPurchaseOrder`) but **not** by the **customer-PO block inside
+`syncSalesOrderFromNetsuite()`**, at three POST sites. Those customer POs are built from the NetSuite
+sales order's `otherRefNum` against the synthetic Agilant vendor, so they carry a `customerId` but a
+**NULL `c_netsuiteInternalPurchaseOrderId`** — which is how to spot them. **1,038 of 1,113** NULL
+`fulfillmentType` PO lines came from this path, so **no cursor rewind would ever have fixed them**;
+the rewind only replays the other path.
+
+Fix: stamp `fulfillmentType` (inherited from the SO line, exactly as `cost` already is) at all three
+create sites, plus a **backfill PUT on the matched-existing-line branch** so pre-existing rows fill
+in on the next sync. Gated by `isset()` on the payload key so non-opted-in clients send nothing, and
+the backfill uses `property_exists` (not `??`) per this file's established ACL-omission rule — an
+ungranted field is **absent**, not null.
+
+**Lesson: before concluding "the backfill is lagging", grep for every writer of the column.** A
+second, un-stamped create path looks identical to a stale cursor from the data side.
+
+### ⚠ A stale child list read at run-start causes FK 1451 on a delete LATER IN THE SAME RUN (fixed 2026-09-17)
+
+`NETSUITE_EXECUTION_MODE_ITEM_FULFILLMENTS` decayed `864000 → 1186 → 396`, stuck `RUNNING`, with one
+item (`b96515b3`) failing five consecutive runs ~every 5 minutes. **Not self-correcting.**
+
+```
+EV-11 ... Error #: 1451 Cannot delete or update a parent row: a foreign key constraint fails
+(Client_Elite.ItemFulfillmentItems_TrackingNumbers ...)
+```
+
+**Root cause is ordering inside a single run, not stale data between runs.** The delete reads an
+item's tracking rows from `$itemFulfillment`, fetched at the **top** of the run — but the tracking
+pass **later in the same run** creates new tracking rows against those same items. The run-start
+snapshot misses them, the child delete skips one, and the item delete hits the FK. Prod proof:
+tracking `0ddc9513` created at **03:31:18**, the item delete failed at **03:31:21** — three seconds
+apart.
+
+Fix, applied at **both** item-level delete sites: **re-read the item's tracking rows live**
+(`GET /v2/item-fulfillment-item-tracking-numbers` joined on `ItemFulfillmentItems.uuid`) immediately
+before deleting, instead of trusting the run-start snapshot — the same re-fetch pattern this file
+already uses for the single-tracking-number fan-out. A `totalRecordCount` guard was added to both.
+
+**Scope was confirmed, not assumed:** every FK-1451 failure that day was on
+`/v2/item-fulfillment-items/` — **zero** on units or tracking rows — so the unit-level lists were
+deliberately left alone.
+
+The exception was **not** swallowed. `send()` throws by default; the throw aborted the run and left
+the mode `RUNNING`. That is the designed fail-loud behaviour working correctly.
+
+**General rule for this engine: any list used to delete children must be re-read immediately before
+the delete if ANY later pass in the same run can create more of them.** A run-start snapshot is only
+safe for read-only use.
+
+### ⚠ NULL `fulfillmentType` on SO lines can be CORRECT ROUTING, not a sync bug (2026-09-17)
+
+"684 `SalesOrderItems` have NULL `fulfillmentType`" looked like a defect and was not. Ruled out in
+order — record these so nobody re-walks them:
+
+1. backfill lag — no,
+2. the `property_exists` gate — no,
+3. ACL on the field — grants exist (`recordFieldId` **2594/2595**, roleId 3, `isWritable = 1`),
+4. a cursor timezone theory — **wrong**; the code correctly uses `America/New_York`.
+
+**Actual reason:** those orders are now classified as **Transfer Orders** (`$0` + `holdInvoice`), so
+the sync routes them to `syncTransferOrderFromNetsuite()` and they never reach the sales-order path
+that stamps the field. The rows are stranded leftovers — exactly what the retirement method above
+cleans up. **When a per-line field is NULL on a set of orders, check the routing branch before the
+writer.**
+
 ### Custom field contract (hardcoded in `common_sync_togasupply.php`)
 
 The engine requests these `c_` fields by literal name per route — every synced client must have
@@ -1653,6 +1773,24 @@ library (or vice versa) crashes GroWrk and Adyen on their next sync run.
   [NetSuite Sync Alert Monitor](../../library/features/netsuite-sync-alert-monitor.md).
 
 ## Change history
+- 2026-09-17 — Four importer changes, all found on Elite. (1) New
+  `App_Api_Toga2::retireStaleSalesOrderForTransferOrder()` retires the stale `SalesOrder` left
+  behind when an order is reclassified as a TransferOrder — 218 Elite duplicates were
+  double-counting inventory and driving `_qtyOnHand` negative; it moves fulfillments and PO bridges
+  to the TO side before deleting, and throws on `InvoiceItems` (no `transferOrderItemId` exists).
+  Bridge direction confirmed **PO-first** from NYCHH row counts. **NOT yet deployed.** (2) The
+  customer-PO block inside `syncSalesOrderFromNetsuite()` never stamped `fulfillmentType` at its
+  three POST sites — 1,038 of 1,113 NULL PO lines came from that second writer, so no cursor rewind
+  could fix them; added the stamp plus a backfill PUT on the matched-line branch. (3) ITEM_FULFILLMENTS
+  froze on **FK 1451 / EV-11** because the tracking-row list was read at run start while a later pass
+  in the **same run** created more rows; both item-level delete sites now re-read tracking live before
+  deleting. (4) Recorded that a NULL per-line `fulfillmentType` can be correct **routing** (the order is
+  now a Transfer Order) rather than a sync bug, with the four dead ends already ruled out. Also noted the
+  PO-sync unfreeze needed a three-layer ACL grant — the field layer fails as a silent 200, see the
+  [ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md).
+  php-reviewer + silent-failure-hunter clean; one open warning (`getTransferOrderItemsByUuid()` has no
+  pagination). (rgirish)
+
 - 2026-09-15 — Added the **full resync recipe** for a deep cursor rewind (the procedure for
   backfilling a newly-stamped item field): the six `NETSUITE_LAST_SYNC_CURSOR_<SECTION>` keys live in
   the **client** DB, the id half **must be `0`** or the seek skips records at the same datetime, the

package/knowledge/2.0/apps/_underscore/features/acl-permission-chain.md

@@ -17,6 +17,7 @@ files:
   - dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql
   - dbchanges2/Client/2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission.sql
   - dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql
+  - dbchanges2/_modules/netsuite/2026-09-17a - StaleSalesOrderRetirementAcl.sql
 ---
 
 ## Summary
@@ -127,6 +128,92 @@ Two distinct failure shapes, and the second is a page-killer:
    endpoint takes the **entitlement** uuid precisely to avoid requesting the joined
    `subscription.uuid` and betting the whole entitlements page on one more grant.
 
+### ⚠⚠ Record access + ZERO readable fields = HTTP **200**, `WZ-1`, and **NO `meta.totalRecordCount`**
+
+The third layer of the chain fails in a shape nothing else does, and it costs hours because
+**nothing lands in the API error log — the call succeeded.**
+
+With `AclRecordPermissions` + expression + logic group all correct, but **no `AclFieldPermissions`
+rows at all** for that role × record, a GET returns:
+
+- HTTP **200** (not 403, not `EZ-2`),
+- message **`WZ-1: "There are no fields in which you are authorized to read"`**,
+- and **`meta.totalRecordCount` is OMITTED entirely** from the envelope.
+
+That last point is the killer. Fail-loud importer code commonly guards on
+`if (!isset($response->meta->totalRecordCount)) { throw ... }` as its "the existence check did not
+run" test — so a pure field-layer gap surfaces as that throw, with a message blaming record ACL,
+while the record ACL is in fact fine.
+
+**Distinguish the three failure shapes before touching any grant:**
+
+| Shape | Missing layer |
+|---|---|
+| 403 `EZ-1` / `No ACL Logic Groups defined for ACL Record Permissions` | record permission or logic group |
+| 403 `EZ-2` naming specific fields (incl. a `uuid` you never asked for) | *some* field grants exist, the named one does not |
+| **200 + `WZ-1` + no `meta.totalRecordCount`** | **`AclFieldPermissions` is completely empty for that role × record** |
+
+**Worked case (Elite, 2026-09-17).** Elite's NetSuite PO sync was dead for days:
+`NETSUITE_EXECUTION_MODE_PURCHASE_ORDERS` sat at `1-RUNNING` with 51 lifetime occurrences of
+`linkPurchaseOrderToTransferOrder: PurchaseOrders_TransferOrders existence check returned no
+totalRecordCount (API role likely lacks ACL read/write on this bridge)`. It was **misdiagnosed
+twice**: the first pass added `AclRecordPermissions` for records 29/325/329 plus `allowDelete` on
+14/15, verified all five rows present with logic groups — and it still failed, because
+`Client_Elite` had **zero** roleId 3 rows in `AclFieldPermissions` for those bridges.
+`Client_Nychh` had all six, which is exactly why linking worked there.
+
+The working set that fixed it (mirrors `Client_Nychh`):
+
+| `Core.Records` id | route | granted `RecordFields` (roleId 3) |
+|---|---|---|
+| **325** | `purchase-orders-transfer-orders` | 2210 `uuid`, 2211 `purchaseOrderId`, 2212 `transferOrderId` |
+| **329** | `purchase-order-items-transfer-order-items` | 2226 `uuid`, 2227 `purchaseOrderItemId`, 2228 `transferOrderItemId` |
+| **29** | `item-fulfillment-items` | 366 `uuid`, 367 `itemFulfillmentId`, 368 `salesOrderItemId`, 369 `quantity`, 2151 `transferOrderItemId` |
+
+**`id` (2209 / 2225 / 365) is deliberately NOT granted** — NYCHH does not grant it either, and the
+sync joins on `uuid` throughout precisely because the numeric `id` is not ACL-readable. Do not "fix"
+its absence.
+
+Result after deploy: `PurchaseOrders_TransferOrders` went **0 → 17** rows and
+`PurchaseOrderItems_TransferOrderItems` **0 → 28** (populated for the first time ever); the PO mode
+recovered to `864000-IDLE` and the cursor moved 2026-02-03 → 2026-03-28.
+
+**Rule: when you add a record grant, add the field grants in the same migration.** A record
+permission with no field permissions is not a partial grant — it is a grant that reads as a
+successful, empty, count-less response.
+
+### ⚠ A multi-client ACL migration must SELF-HEAL — every tenant is broken differently
+
+Do not write a fleet-wide ACL migration as "insert the rows the reference client has." Surveying
+five `netsuite` clients on 2026-09-17 found **five different broken states** for the same set of
+records:
+
+| Tenant | State found |
+|---|---|
+| **NYCHH** | complete and correct — the reference |
+| **Elite** | records 325/329 missing entirely |
+| **GroWrk** | 325/329 missing **and** record 15 has a permission with **zero logic groups** (silently denies) |
+| **Prudential** | 325/329 exist **twice each** (duplicate permission rows), no expressions, no logic groups |
+| **Canon, Quad** | only 14/15, both with `allowDelete = 0` |
+
+The six-step shape that survives all of them — every step `NOT EXISTS`-guarded and re-runnable:
+
+1. `UPDATE` `allowDelete = 1` on the records that already have permissions (14/15).
+2. `INSERT` `AclRecordPermissions` for the missing records (29/325/329).
+3. `INSERT` `AclRecordExpressions` `'all'` for **all five** records — not just the new three.
+   Prudential already had permissions on 325/329 with **no expression**.
+4. `INSERT` `AclLogicGroups` for **any** permission lacking one — this is what catches GroWrk's
+   orphan permission and Prudential's duplicates, which a "new records only" migration walks past.
+5. `INSERT` `AclLogicGroupExpressions` joining on **`MIN(id)` per record**, not on the expression
+   slug. Prudential has **three** `'all'` expressions on record 14; joining by slug alone fans out
+   into a cross product.
+6. `INSERT` `AclFieldPermissions` — the layer the first attempt missed (see the section above).
+
+**The `MIN(id)` and orphan-logic-group guards came from real production rows, not from theory.**
+Before writing a fleet migration, survey the tenants and let the worst state design the guards.
+Applies to every module that ships to many clients (this one goes to all **22** clients carrying
+`netsuite` in `dbchanges2/_modules.txt`).
+
 ### ⚠ Resolve `Core.RecordFields` ids by HARDCODED LITERAL in a `Client_*` migration — the subselect cannot run
 
 This **overrides** the general "resolve by subselect, never hardcode" rule *for Core lookups from a
@@ -771,6 +858,16 @@ hardcoded `Core.RecordFields` id literals instead of a subselect.
       and every repo is on the **same branch** so the generated model matches the DB.
 
 ## Change history
+- 2026-09-17 — Added the **field-layer silent-200** failure shape: record access with **zero**
+  `AclFieldPermissions` rows returns HTTP **200** carrying `WZ-1` and **omits**
+  `meta.totalRecordCount`, so fail-loud code that guards on that key throws while blaming record
+  ACL — and nothing appears in the API error log because the call succeeded. Verified on
+  `Client_Elite` (records 29/325/329, roleId 3) after the bug was misdiagnosed twice as a record
+  permission gap; recorded the exact `RecordFields` granted (and that `id` is deliberately not).
+  Also added the **self-healing fleet migration** rule — a survey of five `netsuite` tenants found
+  five different broken states (missing rows, an orphan logic group, duplicate permissions,
+  `allowDelete = 0`), so a multi-client ACL migration must guard every step with `NOT EXISTS` and
+  join logic-group expressions on `MIN(id)` per record rather than on the expression slug. (rgirish)
 - 2026-09-17 — Added the **restrictive-expression-is-dead** rule: permissions are collected per role
   and **any** match authorizes, so a row-restricting expression on one role is cancelled by an `'all'`
   grant on another role the same user holds. Verified in `Client_Compass`: expression **235** on role

package/knowledge/2.0/apps/_underscore/features/calculated-sql-fields.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-14
-owners: [snaredla, jcardinal, bala, apeterson]
+updated: 2026-09-17
+owners: [snaredla, jcardinal, bala, apeterson, rgirish]
 files:
   - _underscore/Model.php
   - _underscore/Model/Client/PurchaseOrder.php
@@ -21,6 +21,8 @@ files:
   - _underscore/Model/Quad/Item.php
   - _underscore/Model/Quad/VendorItem.php
   - _underscore/Model/Nychh/Unit.php
+  - _underscore/Model/Client/Item.php
+  - _underscore/Model/Elite/Item.php
   - dbchanges2/Client_Nychh/2026-09-10a - UnitsForPoTableViewRebaseAndTransferLocationField.sql
   - dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql
   - dbchanges2/Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql
@@ -35,6 +37,7 @@ related:
   - ./sales-order-purchase-order-bridge-direction.md
   - ../../../../clients/nychh/features/location-shipping-addresses.md
   - ../../toga25-supply/features/transfer-orders-page.md
+  - ../../../clients/elite/features/inventory-quantities-drop-ship.md
 ---
 
 ## Summary
@@ -218,6 +221,26 @@ characters — that is the standard of evidence for touching a field that runs o
 > even for a client whose subclass overrides it. `_Model_Compass_SalesOrder` has exactly this in its
 > ApprovalDecision notification query. Late static binding only happens with `static::`.
 
+### ⚠ `_Model_Client_Item`'s four composites were `self::` until 2026-09-17 — 25 client models affected
+
+A live instance of the `self::` trap above, now fixed, worth knowing because it silently changed
+behaviour for every tenant.
+
+`_Model_Client_Item`'s four **composite** calculated fields — `_qtyOnHand`, `_qtyAvailable`,
+`_qtyBackordered`, `_qtyOnOrder` — built their SQL from the leaf `_qty*` methods using **`self::`**.
+So a client subclass that overrode a *leaf* method (e.g. `_qtyReceived`) had the override **silently
+ignored** by the inherited composites; the only way to make it stick was to re-declare all four
+composites verbatim on the child. `_Model_Client_PurchaseOrderItem` already used `static::`.
+
+Changed to **`static::`** on 2026-09-17, matching the PurchaseOrderItem model. **This affects all 25
+client `Item` models:** any client already overriding a leaf method now has that override picked up
+by the composites for the first time. **`Nychh` overrides `_qtyReceived` and `_qtyCommitted`, so it
+is the one to watch.**
+
+**Lesson for any shared base model:** write composites with `static::` from the start. A `self::`
+composite does not fail — it quietly returns the parent's number, and the child's override looks
+like it "did nothing."
+
 ## Filtering on a calculated field through the V2 API — it works, bare name only
 
 A calculated field **can** be used in a V2 `where`, and it is the cheapest way to cut a big list —
@@ -268,6 +291,14 @@ Keep the expression cheap, or expect callers to pay for it on every list.
   [save-cascade stored-field deadlocks](./model-save-parent-cascade-stored-field-deadlock.md).
 
 ## Change history
+- 2026-09-17 — Recorded a live instance of the `self::` trap: `_Model_Client_Item`'s four composite
+  fields (`_qtyOnHand`, `_qtyAvailable`, `_qtyBackordered`, `_qtyOnOrder`) used **`self::`**, so a
+  client subclass overriding a *leaf* `_qty*` method was silently ignored unless it re-declared all
+  four composites. Switched to **`static::`**, matching `_Model_Client_PurchaseOrderItem`. This
+  changes behaviour for **all 25 client `Item` models** — `Nychh` (overrides `_qtyReceived` and
+  `_qtyCommitted`) is the one to watch. Found while adding Elite's drop-ship exclusion; see
+  [Elite inventory quantities](../../../clients/elite/features/inventory-quantities-drop-ship.md).
+  (rgirish)
 - 2026-09-14 — Added a **Filtering** section: a calculated field IS usable in a V2 `where` with the
   bare (non-table-prefixed) name, which contradicts a belief written into several frontend repos.
   Mechanism and cost figures cross-referenced to the api2 query contract rather than duplicated.

package/knowledge/2.0/apps/api2/features/v2-rest-query-contract.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-09-14
+updated: 2026-09-17
 owners: [tcox, bala, apeterson, jcardinal, rgirish]
 files:
   - api2/Component/Api/V2/V2.php
@@ -469,6 +469,25 @@ ACL gate for calculated fields lives at **:7216** in `getFullModelData()` — wh
 - **`meta.prohibitedRecordCount`** (set only when `totalRecordCount` is 0) distinguishes
   "ACL hid every row" from "there genuinely are none."
 
+## Bulk DELETE by `where` EXISTS — and you should not use it
+
+A `DELETE` with **no uuid** plus a `where` clause is fully implemented: `V2.php:5554` is the branch,
+`:5697` builds a `SELECT id` with ACL applied, `:5740` loops the ids and calls `$model->delete()`.
+It returns `meta.deletedRecordCount`. Verified 2026-09-17.
+
+**Three reasons it was rejected for the 1.0 NetSuite importer, and the third is decisive:**
+
+1. **Zero callers anywhere in the codebase.** All 20 deletes in `library/app/api/toga2.php` are by
+   uuid. There is no proven path.
+2. **It is not atomic.** It loops rows, collects per-row errors, and does **no rollback** — a partial
+   failure still returns `200`.
+3. **⚠ Zero matching rows sets `$isPermitted = false` (`V2.php:5732`) and returns an
+   UNAUTHORIZED-shaped error.** "Nothing to delete" is indistinguishable from "you may not delete
+   this", so any fail-loud caller will misread a clean no-op as an **ACL gap** and go hunting through
+   `AclRecordPermissions` for a bug that does not exist.
+
+If you need the behaviour, loop uuids client-side. Point 3 is the durable, non-obvious fact.
+
 ## Serialization quirks
 
 - **Datetimes on a primary table** serialize as ISO-8601 with a **Central offset** (no
@@ -521,6 +540,12 @@ ACL gate for calculated fields lives at **:7216** in `getFullModelData()` — wh
   [V2 request logging](request-logging.md).
 
 ## Change history
+- 2026-09-17 — Documented that **bulk `DELETE` by `where` is implemented but unused and unsafe to
+  adopt**: the branch is real (`V2.php:5554` / `:5697` / `:5740`, returns `meta.deletedRecordCount`)
+  but has zero callers, is non-atomic with no rollback, and — the decisive part — **zero matching
+  rows sets `$isPermitted = false` (`:5732`) and returns an UNAUTHORIZED-shaped error**, so a clean
+  no-op reads as an ACL denial. Recorded after it was considered and rejected for the 1.0 NetSuite
+  importer's stale-SalesOrder retirement. No code changed. (rgirish)
 - 2026-09-14 — **Corrected a wrong team-wide belief: a `where` on a calculated (`FIELD_SQL`) field
   WORKS, with the BARE field name.** `_qtyAvailable:ge:1` is inlined into the `WHERE` and returns 200
   with a correct `totalRecordCount`; only the table-prefixed `Table._qtyAvailable` form is routed to a

package/knowledge/INDEX.md

@@ -19,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 87 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 88 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 69 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 26 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 19 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/knowledge/clients/elite/INDEX.md

@@ -2,6 +2,7 @@
 
 | Doc | Framework | Summary |
 |-----|-----------|---------|
+| [Elite inventory quantities — drop ship is excluded from On Hand / Available ONLY](features/inventory-quantities-drop-ship.md) | 2.0 | Elite's Inventory page showed **negative Qty On Hand / Qty Available** (worst: `SVC-CI-RETAINER-RS` at **-235**). |
 | [Elite — NetSuite → TOGa Supply inbound sync (TRUE-80499 onboarding)](features/netsuite-togasupply-sync.md) | 1.0 | Elite is the 18th client on the shared NetSuite → TOGa Supply importer ([engine](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md)). |
 | [Elite SalesOrder → NetSuite Push (postPost/postPut interceptors → worker2)](features/salesorder-netsuite-push.md) | 2.0 | Elite orders created in Toga are pushed into NetSuite **event-driven**, not on a cron. |
 | [Elite — Sales Order stage change posts a reply on the TOGa Desk (1.0) ticket](features/salesorder-status-togadesk-reply.md) | 2.0 | When an Elite sales order's **stage** changes, a reply is posted on the originating **TOGa Desk (1.0)** ticket so the requester sees progress where they raised |

package/knowledge/clients/elite/features/inventory-quantities-drop-ship.md

@@ -0,0 +1,89 @@
+---
+title: "Elite inventory quantities — drop ship is excluded from On Hand / Available ONLY"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: elite
+type: client-feature
+status: active
+updated: 2026-09-17
+owners: [rgirish]
+files:
+  - _underscore/Model/Elite/Item.php
+  - _underscore/Model/Client/Item.php
+related:
+  - ../profile.md
+  - ./netsuite-togasupply-sync.md
+  - ../../../2.0/apps/_underscore/features/calculated-sql-fields.md
+  - ../../nychh/features/transfer-order-inventory-quantities.md
+  - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
+---
+
+## Summary
+
+Elite's Inventory page showed **negative Qty On Hand / Qty Available** (worst:
+`SVC-CI-RETAINER-RS` at **-235**). Cause: **drop-ship lines are fulfilled but never received into
+stock**, so the base `received - fulfilled` arithmetic went negative.
+
+The rule Elite runs on: **exclude drop ship from `_qtyOnHand` and `_qtyAvailable` ONLY.** Every
+other quantity counts **all** lines — a drop-ship line really was ordered and really did ship.
+
+## How it works
+
+Two `private static` helpers on `_Model_Elite_Item`, used **only** by the two composites:
+
+| Helper | Used by |
+|---|---|
+| `qtyFulfilledStockOnly()` | `_qtyOnHand` |
+| `qtyCommittedStockOnly()` | `_qtyAvailable` |
+
+`_qtyFulfilled` and `_qtyCommitted` themselves stay **inherited and unfiltered** — the filtering
+lives in the composites, not in the leaf fields, so anything reading the leaf number still sees the
+true shipped/committed total.
+
+**Quantities that count ALL lines (drop ship included):** `_qtyOrdered`, `_qtyFulfilled`,
+`_qtyInvoiced`, `_qtyBackordered`, `_qtyOnOrder`.
+
+### Two deliberate decisions — do not "improve" either
+
+- **No `GREATEST(..., 0)` floor.** Negatives must stay **visible** so the underlying data problem
+  can be traced. Flooring hides a real defect behind a clean-looking zero. This was decided
+  explicitly, after one iteration.
+- **A NULL `fulfillmentType` is NOT treated as `STOCK`.** Only a line positively marked stock counts
+  toward on-hand. (NULL `fulfillmentType` has its own causes — see the
+  [importer doc](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).)
+
+### The base model had to change too (`self::` → `static::`)
+
+`_Model_Client_Item`'s four composites (`_qtyOnHand`, `_qtyAvailable`, `_qtyBackordered`,
+`_qtyOnOrder`) called their leaf methods with **`self::`**, which silently ignores a child override.
+They were switched to **`static::`** in the same session. That is a **framework-level** change
+affecting **all 25 client `Item` models** — full detail and the NYCHH watch item on
+[FIELD_SQL calculated fields](../../../2.0/apps/_underscore/features/calculated-sql-fields.md).
+
+## Verification
+
+Run against prod data after the change: **0 negatives on all 79 non-service items.** The **7**
+remaining negatives are all `SVC-` service items (received 0, fulfilled > 0), which the developer
+explicitly said to ignore.
+
+## Gotchas / known issues
+
+- **The Inventory TableView still filters services by `(Items.partNumber:excludes:SVC-)`**, which
+  **misses 18 service items** that sit under service `ItemClasses` trees but carry normal part
+  numbers. Undecided and not implemented. Facts established while investigating:
+  - **`_isServiceClass` does not exist** anywhere in the code (grepped all of `Model/` and
+    `Trait/`) — the migration comment referencing it is **stale**.
+  - The table is **`ItemClasses`**, not `ItemClassifications`, and it is a **tree**
+    (`parentItemClassId`).
+  - Service roots are **Lifecycle Services (1)**, **Advisory and Modernization (22)**, **True
+    Partner Services (40)** — but **6 non-service items** sit under the latter two, so matching on
+    root alone is too broad.
+
+## Change history
+- 2026-09-17 — Documented Elite's drop-ship exclusion rule: drop ship is removed from `_qtyOnHand`
+  and `_qtyAvailable` only, via two `private static` helpers, while every other `_qty*` counts all
+  lines; no `GREATEST` floor (negatives must stay visible) and NULL `fulfillmentType` is not treated
+  as stock. Verified 0 negatives on all 79 non-service items in prod. Also recorded the paired base
+  change from `self::` to `static::` on `_Model_Client_Item`'s composites, and the open
+  `partNumber:excludes:SVC-` TableView filter that misses 18 service items. (rgirish)

package/knowledge/clients/elite/features/netsuite-togasupply-sync.md

@@ -6,7 +6,7 @@ project: Worker
 client: elite
 type: client-feature
 status: active
-updated: 2026-09-15
+updated: 2026-09-17
 owners: ["snaredla", "jcardinal", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/sync_togasupply_elite.php
@@ -22,6 +22,7 @@ files:
   - api2/Component/Api/V2/V2.php
   - dbchanges2/Client_Elite/_modules.txt
   - dbchanges2/Client_Elite/2026-09-04a - EliteItemAssetTypeApiWritePermission.sql
+  - dbchanges2/_modules/netsuite/2026-09-17a - StaleSalesOrderRetirementAcl.sql
   - library/app/api/toga2.php
   - library/app/api/netsuite/rest.php
 related:
@@ -36,6 +37,8 @@ related:
   - ../../growrk/features/transfer-order-flow.md
   - ../../../2.0/apps/api2/features/nested-relationship-writes.md
   - ../../../2.0/apps/dbchanges2/workflows/client-schema-drift-audit.md
+  - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
+  - ./inventory-quantities-drop-ship.md
 ---
 
 ## Summary
@@ -299,12 +302,72 @@ Records **15, 18, 21, 105 are all `aclDatabase = CLIENT`**, so every one of thes
 logic groups on id 346, from the unguarded `2026-09-11c` migration. Harmless, but see the
 [item-class doc](../../../1.0/apps/library/features/netsuite-item-class-sync.md) before cleaning.
 
+## ⚠ 2026-09-17 incident — PO sync dead for days on a three-layer ACL gap (FIXED + DEPLOYED)
+
+**Symptom:** `NETSUITE_EXECUTION_MODE_PURCHASE_ORDERS` stuck at **`1-RUNNING`** (a one-second
+window) with the PO cursor crawling ~5 seconds of NetSuite time per run. **51** lifetime
+occurrences of:
+
+```
+linkPurchaseOrderToTransferOrder: PurchaseOrders_TransferOrders existence check returned no
+totalRecordCount (API role likely lacks ACL read/write on this bridge)
+```
+
+**Misdiagnosed twice before it landed — that is the lesson.** The first pass added
+`AclRecordPermissions` for records 29/325/329 plus `allowDelete` on 14/15, verified all five rows
+present with logic groups, and it **still failed**. The real gap was the **third** layer:
+`Client_Elite` had **zero** roleId 3 rows in `AclFieldPermissions` for those bridges. With record
+access but no readable fields, api2 returns **HTTP 200** carrying
+**`WZ-1: "There are no fields in which you are authorized to read"`** and **omits
+`meta.totalRecordCount`** — which is exactly what the importer throws on. **Nothing appears in the
+API error log, because the call succeeded.** `Client_Nychh` had all six field grants, which is why
+linking worked there.
+
+The grants applied (mirroring `Client_Nychh`):
+
+| Record | Route | `RecordFields` granted (roleId 3) |
+|---|---|---|
+| 325 | `purchase-orders-transfer-orders` | 2210 `uuid`, 2211 `purchaseOrderId`, 2212 `transferOrderId` |
+| 329 | `purchase-order-items-transfer-order-items` | 2226 `uuid`, 2227 `purchaseOrderItemId`, 2228 `transferOrderItemId` |
+| 29 | `item-fulfillment-items` | 366 `uuid`, 367 `itemFulfillmentId`, 368 `salesOrderItemId`, 369 `quantity`, 2151 `transferOrderItemId` |
+
+`id` (2209 / 2225 / 365) is **deliberately not granted** — NYCHH does not grant it either, and the
+sync joins on `uuid` throughout because the numeric id is not ACL-readable.
+
+**Verified after deploy:** `PurchaseOrders_TransferOrders` **0 → 17** rows and
+`PurchaseOrderItems_TransferOrderItems` **0 → 28** — populated for the first time ever. PO mode
+recovered to `864000-IDLE`; cursor moved 2026-02-03 → 2026-03-28.
+
+**Migration:** `dbchanges2/_modules/netsuite/2026-09-17a - StaleSalesOrderRetirementAcl.sql`. It
+ships to **all 22 clients** carrying `netsuite` in `_modules.txt` and is written to **self-heal**
+(five tenants were each broken differently) — the design rules are on the
+[ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md). **Run so far
+on `Client_Elite` only.**
+
+### Elite's stale SalesOrder backfill is queued, not done
+
+Enabling transfer-order detection left **218** Elite `SalesOrders` that duplicate a `TransferOrder`
+(**217 of 217** matched pairs identical on order number, line count and total quantity). They still
+carry fulfillments, which is what drove `_qtyOnHand` negative — see
+[inventory quantities](./inventory-quantities-drop-ship.md). The retirement method that cleans them
+up is built but **NOT yet deployed**; mechanics on the
+[engine doc](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
+
+Two blockers to clear by hand first:
+
+1. **SalesOrder 240734 has 4 `InvoiceItems` and WILL throw** — `InvoiceItems` has no
+   `transferOrderItemId`, so those rows cannot be moved. Deliberate fail-loud; it blocks the
+   backfill until resolved.
+2. **11 of the 218 have no matching TransferOrder** (4 are TOGa-created `SA1000xx` with no NetSuite
+   id). Manual review.
+
 ## Gotchas / known issues
 
 - **⚠ OPEN, unrelated: `GET /v2/notes/{uuid}/files` returns 405 `EV-7`** ("method not allowed /
   route does not exist") repeatedly for Elite. Found while diagnosing the 2026-09-08 transfer-order
   incident; it is **not** part of it. It does **not** abort the sync, and it was still occurring
-  after the identifier fix. Needs its own ticket.
+  after the identifier fix. **Still open and still unticketed — reconfirmed 2026-09-17.** Needs its
+  own ticket.
 
 - **⚠ Two files named `sync_togasupply_elite.php`, both scheduled.**
   `worker/crons/toga2/netsuite/sync_togasupply_elite.php` (`*/5`) is **this** supply importer;
@@ -339,6 +402,17 @@ logic groups on id 346, from the unguarded `2026-09-11c` migration. Harmless, bu
   rewinding `NETSUITE_LAST_SYNC_DATETIME_SALES_ORDERS`.
 
 ## Change history
+- 2026-09-17 — **PO sync was dead for days on a three-layer ACL gap — fixed and deployed.**
+  `NETSUITE_EXECUTION_MODE_PURCHASE_ORDERS` sat at `1-RUNNING` with 51 occurrences of the
+  `linkPurchaseOrderToTransferOrder ... no totalRecordCount` throw. Misdiagnosed twice as a record
+  permission gap; the real gap was `AclFieldPermissions` — `Client_Elite` had zero roleId 3 field
+  rows for records 29/325/329, and api2 answers that with **200 + `WZ-1` + no
+  `meta.totalRecordCount`**, leaving no trace in the API error log. Recorded the exact fields granted
+  (and that `id` is deliberately not). Bridges went 0→17 and 0→28 rows; mode back to `864000-IDLE`,
+  cursor 2026-02-03 → 2026-03-28. Migration `_modules/netsuite/2026-09-17a` ships to all 22 netsuite
+  clients but has been run on `Client_Elite` only. Also recorded the **218 stale SalesOrders**
+  backfill as queued-not-done, with SO 240734 (4 `InvoiceItems`) and 11 unmatched orders as manual
+  blockers, and reconfirmed the `GET /v2/notes/{uuid}/files` 405 `EV-7` is still open. (rgirish)
 
 - 2026-09-15 — **itemClass + line `fulfillmentType` are now on for Elite, and Elite alone.** Recorded
   the two wrapper constants (`IS_ENABLED_NETSUITE_ITEM_CLASSIFICATIONS`,

package/knowledge/clients/elite/profile.md

@@ -16,7 +16,7 @@ project: Worker
 client: elite
 type: profile
 status: active
-updated: 2026-09-08
+updated: 2026-09-17
 owners: [snaredla, apeterson, tcox, bala, rgirish]
 files:
   - worker2/Worker/Elite.php
@@ -25,6 +25,7 @@ files:
   - library/app/api/servicerequest.php
   - _underscore/Model/Elite/SalesOrder.php
   - _underscore/Model/Elite/ServiceRequest.php
+  - _underscore/Model/Elite/Item.php
   - togadesk/desk/includes/classes/class.ticket.php
   - worker/crons/toga2/netsuite/sync_togasupply_elite.php
 related:
@@ -36,6 +37,7 @@ related:
   - features/salesorder-netsuite-push.md
   - features/togadesk-service-request-intake.md
   - features/salesorder-status-togadesk-reply.md
+  - features/inventory-quantities-drop-ship.md
   - 2.0/apps/worker2/features/service-request-sales-order-generation.md
 ---
 

package/package.json

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