toga-ai 1.0.834 → 1.0.835

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/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/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/package.json

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