toga-ai 1.0.834 → 1.0.836

package/knowledge/1.0/apps/library/features/netsuite-item-class-sync.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-09-15
+updated: 2026-09-17
 owners: [rgirish]
 files:
   - library/app/api/toga2.php
@@ -23,6 +23,7 @@ related:
   - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
   - ../../../2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md
   - ../../../clients/elite/features/netsuite-togasupply-sync.md
+  - ../../../clients/elite/features/supply2-tableview-config-drift.md
 ---
 
 ## Summary
@@ -138,7 +139,20 @@ without `AclRecordPermissions` the API role cannot `POST /item-classes` at all.
   sync re-walks transactions that reference them. That needs a
   [cursor rewind](../../worker/features/netsuite-togasupply-per-client-sync.md).
 
+- **The tree depth is not capped — consumers that walk it with fixed joins can break silently.**
+  `Client_Elite` is exactly **5 levels** deep today (4 roots: 1 Lifecycle Services, 4 Technology
+  Sales, 22 Advisory and Modernization, 40 True Partner Services; verified 2026-09-15 that every
+  5-level chain ends at a true root). Nothing stops NetSuite adding a 6th level. Anything that
+  resolves an item to its root class with a fixed number of `LEFT JOIN`s — such as Elite's
+  [Inventory service-item filter](../../../clients/elite/features/supply2-tableview-config-drift.md) —
+  will then silently mis-classify the deeper items with no error. Re-check depth when the NetSuite
+  tree changes.
+
 ## Change history
+- 2026-09-17 — Added the **unbounded tree depth** caveat: `Client_Elite` is exactly 5 levels with 4
+  roots (1 / 4 / 22 / 40) and every chain verified to end at a true root, but nothing caps depth, so
+  any consumer walking to the root with a fixed join count breaks silently if NetSuite adds a level.
+  No code change. (rgirish)
 - 2026-09-15 — Documented the feature from an audit of the deployed code (library `37b55595`, worker
   `6637ae75`). **Found and fixed a field-name mismatch that made the feature a complete no-op since
   deploy:** the PHP sent `c_netsuiteInternalItemClassId` in 5 places while the live column and

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/tableview-apiwhereclause-row-filtering.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-09-01
-owners: ["bala"]
+updated: 2026-09-17
+owners: ["bala", "rgirish"]
 files:
   - api2/Component/Api/V2/V2.php
   - _underscore/Model/Client/TableView.php
@@ -15,6 +15,7 @@ files:
 related:
   - ../../../clients/compass-usa/features/item-fulfillment-tracking-tableview.md
   - ../../../clients/compass-usa/features/item-catalogs-and-duplicate-items.md
+  - ../../../clients/elite/features/supply2-tableview-config-drift.md
   - tableview-field-metadata.md
 ---
 
@@ -86,6 +87,34 @@ the existing Compass convention and the stored clauses stay uniform whether they
 or five. (The "expression field must not start with `(`" gotcha below is about the *field slot* of a
 condition **after** the wrapper is removed — the two are not in conflict.)
 
+### Subqueries ARE possible — use `/**/` in place of every space
+
+The parser splits the stored clause on **literal spaces**, so a normal SQL subquery (which needs
+spaces) cannot be stored in `apiWhereClause`. The way around it: write `/**/` instead of every
+space. MySQL treats `/**/` as whitespace, and the parser sees no space at all. That makes an
+arbitrary **correlated subquery** usable as the *field* side of a condition.
+
+```
+(SELECT/**/c5.id/**/FROM/**/ItemClasses/**/c1/**/WHERE/**/c1.id=Items.itemClassId):notin:1:22:40
+```
+
+Confirmed by reading `parseOptionsWhere` and simulating it in PHP (2026-09-17):
+
+- Conditions split on `,` **only at matching paren depth** — commas nested deeper (e.g. inside a
+  `COALESCE(a,b,c)` within the subquery) are safe.
+- Each condition then splits on `:` into field / operator / value.
+- **The field side passes through to SQL unescaped**, so it can be any expression that has no
+  literal space, `:` or `,` at top depth.
+- `notin` splits its value on `:`, so `:notin:1:22:40` becomes the IN-list `(1,22,40)`.
+
+**Precedent:** Elite's prod clause on slug `item-fulfillments-for-sales-orders` already uses this
+same `/**/` trick with a `CONCAT((SELECT ...))` subquery, so it is an established pattern, not a
+one-off.
+
+**Caveat — leave a comment.** This is powerful but it makes the stored clause hard to read for
+anyone looking straight at `TableViews`. Always add a `--` comment in the migration explaining
+what the subquery does.
+
 ### Join alias rule (which table-qualified name to use)
 
 In `_underscore/Model/Client/TableView.php` (~line 89-96), the **first** occurrence of a joined
@@ -129,12 +158,27 @@ None — engine behavior. A specific client's view may carry its own `apiWhereCl
   starts with a letter (e.g. `IFNULL(...)`), never a bare parenthesized expression.
 - **NULL FKs drop silently.** A plain `field:ne:x` excludes rows where `field IS NULL` too. Wrap
   nullable columns in `IFNULL(col,<sentinel>)` when the intent is "exclude only these values."
+- **A literal space ends the clause element** — that is why a subquery needs `/**/` for every
+  space (see above). The same applies to any expression field: no spaces, anywhere.
+- **Filter on ids, not names.** Names in lookup tables are free-text imported from NetSuite and
+  can be renamed without the id changing, so a `name LIKE` match is the fragile choice. Proven on
+  Elite: filtering root classes by `name LIKE '%Services%'` left 94 items visible instead of the
+  correct 82, because "Advisory and Modernization" contains no "Services".
 - **Operator allowlist.** `parseOptionsWhere` whitelists the operators above and rejects unknown
   ones (e.g. `regexp` returns a 500) — see the Compass cost-centers doc. Numeric/regex filtering
   that the grammar can't express must be done client-side or by adding an operator to api2.
 
 ## Change history
 
+- 2026-09-17 — **Recorded that subqueries ARE possible in a stored `apiWhereClause`**: the parser
+  splits on literal spaces, so writing `/**/` in place of every space (MySQL reads it as
+  whitespace, the parser sees no space) lets an arbitrary correlated subquery act as the field
+  side of a condition. Confirmed the parser mechanics by reading `parseOptionsWhere` and
+  simulating it in PHP — commas split only at matching paren depth, the field side passes to SQL
+  unescaped, and `notin` splits its value on `:` so `:notin:1:22:40` yields the IN-list (1,22,40).
+  Noted the existing prod precedent (Elite's `item-fulfillments-for-sales-orders` clause already
+  uses `CONCAT((SELECT ...))` this way), and added the "filter on ids, not names" gotcha —
+  name-matching left 94 Elite items visible instead of 82. No code change. (rgirish)
 - 2026-09-01 — Recorded that the parser **strips one leading `(` and one trailing `)` from the whole
   clause before splitting**, so the wrapped single-condition form `(Items.catalogId:eq:1)` is safe
   and is the house convention (this was previously only documented for the multi-condition form).

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/features/supply2-tableview-config-drift.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: elite
 type: client-feature
 status: active
-updated: 2026-09-04
+updated: 2026-09-17
 owners: [tcox, bala, rgirish]
 files:
   - dbchanges2/Client_Elite/
@@ -14,6 +14,7 @@ files:
   - dbchanges2/Client_Elite/2026-08-17 - FulfillmentTableViews.sql
   - dbchanges2/Client_Elite/2026-08-13a - InventoryGroupingsSurfaceOverrides.sql
   - dbchanges2/Client_Elite/2026-09-04b - EliteInventoryHideServiceItems.sql
+  - dbchanges2/Client_Elite/2026-09-15a - InventoryHideServiceClassItems.sql
   - dbchanges2/Core/2026-08-07 - ServiceRequests TableView.sql
   - dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql
   - dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql
@@ -25,6 +26,8 @@ related:
   - ../../../2.0/apps/_underscore/features/tracking-number-bridges.md
   - ../../../2.0/apps/_underscore/features/units-for-items-for-purchase-orders.md
   - ../../../2.0/apps/_underscore/features/page-meta-context-field-settings.md
+  - ../../../1.0/apps/library/features/netsuite-item-class-sync.md
+  - ../../../2.0/apps/_underscore/features/item-classification-itemclasses.md
 ---
 
 ## Summary
@@ -276,33 +279,106 @@ the live Units view is `inventory_units` (`TableViews` id 21), not
 This pairs with the existing team rule that **a committed migration records intent, not deployed
 state** — the frontend repo records the *default*, not this client's state.
 
-## Hiding service lines from Inventory — `2026-09-04b`
+## Hiding service lines from Inventory — `2026-09-04b`, replaced by `2026-09-15a`
 
-`2026-09-04b - EliteInventoryHideServiceItems.sql` sets `TableViews.apiWhereClause`:
+> **⚠ Current rule (2026-09-15): service items are hidden by their ROOT ItemClass, not by the
+> `SVC-` partNumber prefix.** `2026-09-15a - InventoryHideServiceClassItems.sql` rewrites the
+> `inventory_items` clause. The 2026-09-04b history below is kept because it explains the
+> `IFNULL(...)` NULL-drop rule, which still applies.
+
+`2026-09-15a - InventoryHideServiceClassItems.sql` rewrites `TableViews.apiWhereClause` for slug
+`inventory_items` in `Client_Elite`. It walks the `ItemClasses` parent chain and excludes any item
+whose **root** ItemClass id is **1** (Lifecycle Services), **22** (Advisory and Modernization) or
+**40** (True Partner Services), using a correlated subquery written with `/**/` as whitespace —
+see [apiWhereClause row filtering](../../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md#subqueries-are-possible--use--in-place-of-every-space)
+for the technique and the parser mechanics.
+
+**No `_underscore` deploy is needed.** The whole check lives in the stored clause. An earlier draft
+required a `_isServiceClass` model field on `_Model_Elite_Item`; **that field does not exist and is
+not needed** — do not add one.
+
+### Why the class check replaced the `SVC-` prefix
+
+The `SVC-` prefix was an unreliable signal. Verified on **prod `Client_Elite`** (2026-09-15):
+
+| Measure | Count |
+|---|---|
+| Items total | 122 |
+| Service items by root ItemClass | 40 |
+| Service items by `SVC-` prefix | 27 |
+| Visible after the class filter | 82 |
+
+The class check catches **18 services the prefix missed** — Cisco `CON-SNT-*` / `CON-ROB-*`
+contracts, `LIC-ENT-*` licenses, `CarePacks - Fixed`, `PROJECT - CABLING`, `CONFIG/INSTALL` — with
+**zero false hides**.
+
+### Match on ids, never on class NAMES
+
+Hardcoded ids 1 / 22 / 40 are the stable reference. Names are free-text imported from NetSuite and
+can be renamed without the id changing. Proven wrong in practice here: filtering on
+`name LIKE '%Services%'` returned **94** visible instead of the correct **82**, because "Advisory
+and Modernization" contains no "Services".
+
+### `Client_Elite` ItemClasses hierarchy (prod, verified 2026-09-15)
+
+The table is **`ItemClasses`**, not `ItemClassifications`. Exactly **4 root rows**
+(`parentItemClassId IS NULL`):
+
+| id | Name | Kind |
+|---|---|---|
+| 1 | Lifecycle Services | service |
+| 4 | Technology Sales | product |
+| 22 | Advisory and Modernization | service |
+| 40 | True Partner Services | service |
+
+Tree depth is exactly **5 levels**, and every 5-level chain terminates at a true root (a query for
+level-5 classes with a non-null parent returned 0 rows). So the migration's fixed 5-alias
+`LEFT JOIN` walk resolves every item to its true root **today**. See
+[the hierarchy import](../../../1.0/apps/library/features/netsuite-item-class-sync.md).
+
+### Unclassified items stay visible — and 5 real services leak
+
+**29 Items have `itemClassId` NULL.** The clause is a blocklist, so unclassified items stay
+**visible** — the safer default, since hiding stock people expect to see is worse than showing a
+few extra lines. But 5 of those 29 are real services by name and will newly appear in Inventory:
+
+- `SVC-FS-SHIPPING-RECLAIM-LAPTOP`
+- `SVC-FS-SHIPPING-SYSTEM SWAP-LAPTOP`
+- `SVC-FS-DEPLOY-GW`
+- `SVC-FS-SHIPPING-2DAY`
+- `SVC-FS-ELITE-PERIPHERAL`
+
+**Open decision left with the developer:** either set an ItemClass on those 5 in NetSuite, or AND
+the old `SVC-` prefix check back into the clause.
+
+### The previous rule — `2026-09-04b` (superseded for `inventory_items`)
+
+`2026-09-04b - EliteInventoryHideServiceItems.sql` set:
 
 | View | Clause |
 |---|---|
-| `inventory_units` | `(IFNULL(Items.assetTypeId,0):ne:2)` |
-| `inventory_items` | `(Items.partNumber:excludes:SVC-,IFNULL(Items.assetTypeId,0):ne:2)` |
+| `inventory_units` | `(IFNULL(Items.assetTypeId,0):ne:2)` — **still in force** |
+| `inventory_items` | `(Items.partNumber:excludes:SVC-,IFNULL(Items.assetTypeId,0):ne:2)` — replaced |
 
-`assetTypeId 2` = Elite's `Services` row. Notes for anyone porting this:
+`assetTypeId 2` = Elite's `Services` row. Notes that still apply to anyone porting this:
 
 - **The filter belongs in the database table view, not the frontend** — an explicit scope decision.
 - **`IFNULL(...,0):ne:2` is mandatory, not cosmetic.** A bare `:ne:2` drops every `NULL` row and
-  would hide **all unstamped items** — and 110 of Elite's 113 items are unstamped until the cursor
-  backfill runs. The shape is copied from Elite's existing `item-fulfillments-for-sales-orders`
-  view. Grammar and the NULL-drop rule:
+  would hide **all unstamped items**. The shape is copied from Elite's existing
+  `item-fulfillments-for-sales-orders` view. Grammar and the NULL-drop rule:
   [apiWhereClause row filtering](../../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md).
-- **The `SVC-` prefix rule is kept on `inventory_items`** because it still catches the three items
-  NetSuite mis-types as `InvtPart` (`SVC-TS-ELITE-HDONBOARDING`, `CONFIG/INSTALL`,
-  `CONF-RM-INSTALL-SUPP`) — see
-  [netsuite-togasupply-sync](./netsuite-togasupply-sync.md).
 - **Both `UPDATE`s are guarded on the current value**, so a re-run is a no-op.
 - `inventory_units` was targeted **because of the `SurfaceOverrides` finding above** — filtering
   view 17 would have had no visible effect for Elite.
 
 ## Gotchas / known issues
 
+- **A 6th NetSuite class level would silently leak services back into Inventory.** The
+  `2026-09-15a` clause walks a **fixed 5-alias** chain because Elite's tree is exactly 5 deep
+  today — but nothing in the schema caps the depth. If NetSuite adds a level under a service root,
+  those items reappear in Inventory with no error. Re-check the depth whenever the classification
+  tree changes.
+
 - **A `Client_*` DB that predates a platform migration fails silently until a user opens the
   view.** Nothing validates `TableViewJoins.parentRecordFieldId` against live `Core.RecordFields`,
   so a deleted id sits there until it 500s. Worth checking for **any** client onboarded before
@@ -312,6 +388,18 @@ state** — the frontend repo records the *default*, not this client's state.
   [error-reporting-issue-event](../../../2.0/apps/_underscore/features/error-reporting-issue-event.md).
 
 ## Change history
+- 2026-09-17 — **Replaced the `SVC-` partNumber prefix filter with an ItemClass-hierarchy check**
+  on the `inventory_items` view (`2026-09-15a - InventoryHideServiceClassItems.sql`): the clause
+  now walks the `ItemClasses` parent chain and excludes items whose ROOT class id is 1, 22 or 40,
+  via a `/**/`-whitespace correlated subquery. Prod numbers: 122 items, 40 service by class vs 27
+  by prefix — the class check catches 18 the prefix missed (Cisco CON-SNT-*/CON-ROB-*, LIC-ENT-*,
+  CarePacks, PROJECT - CABLING, CONFIG/INSTALL) with zero false hides; 82 visible after filtering.
+  **No `_underscore` deploy** — an earlier draft's `_isServiceClass` model field does not exist and
+  is not needed. Recorded the verified `Client_Elite` hierarchy (4 roots, exactly 5 levels, every
+  chain terminating at a true root) and the decision to match on **ids, not names** (a
+  `name LIKE '%Services%'` filter left 94 visible, not 82, because "Advisory and Modernization"
+  has no "Services" in it). Open item: 29 items have a NULL `itemClassId` and stay visible by
+  design, but 5 of them are real services and will newly appear. (rgirish)
 - 2026-09-04 — **Corrected which table view Elite's Inventory page actually reads, then filtered
   it.** `toga25-supply/src` shows the DEFAULT groupings using `inventory_items` +
   `units-for-items-for-purchase-orders`, and `inventory_units` appears nowhere in `src` — reading as

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.834",
+  "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",