toga-ai 1.0.913 → 1.0.914

package/knowledge/2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-09-17
+updated: 2026-09-29
 owners: ["bala", "rgirish"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -17,6 +17,7 @@ related:
   - ../../../clients/compass-usa/features/item-catalogs-and-duplicate-items.md
   - ../../../clients/elite/features/supply2-tableview-config-drift.md
   - tableview-field-metadata.md
+  - ../../_underscore/features/calculated-sql-fields.md
 ---
 
 ## Summary
@@ -167,8 +168,40 @@ None — engine behavior. A specific client's view may carry its own `apiWhereCl
 - **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.
+- **⚠ The FIELD name is never validated — an unknown one is a bare 500 with an EMPTY body.**
+  `parseOptionsWhere` maps only the operator token; the field slot passes straight into the SQL.
+  A name no model declares reaches MySQL as `Unknown column '<x>' in 'where clause'`, nothing
+  catches it, and the request dies as a 500 with **no message at all** (the 1.0 monitor then reports
+  its fallback literal *"No message found in response payload"* — see
+  [v2-api-error-codes](v2-api-error-codes.md) note 13). Live case: a `_isServiceClass` condition
+  stored on Elite's `inventory_items` clause 500'd `GET /v2/items` **91 times in 5 minutes across
+  7 prod api2 instances** (2026-09-17). **Open gap:** api2 has no guard that rejects an unknown
+  `_`-prefixed field with a 400 before it reaches MySQL.
+- **⚠ Deploy order: the `_underscore` model field ships BEFORE the migration that references it.**
+  An `_`-prefixed name in a clause only resolves if the model declares it `FIELD_SQL` with a
+  matching same-name static (e.g. `_qtyOnHand` on `_Model_Client_Item`) — see
+  [calculated SQL fields](../../_underscore/features/calculated-sql-fields.md). A clause is **data**,
+  so it goes live the instant the `dbchanges2` file runs, with no deploy gate; applying it first
+  takes the listing endpoint down for that tenant. Check the client's own model too — a
+  `_Model_<Client>_Item` inherits from `_Model_Client_Item` and may declare neither.
+- **An unexplained field in a `where=` lives in the DB, not the frontend.** Filters reaching api2
+  are stored in `Client_<Tenant>.TableViews.apiWhereClause`, not written in app code. When a field
+  name appears in **no** repo and **no** git history, query `TableViews` across the client DBs —
+  that is where it is.
 
 ## Change history
+- 2026-09-29 — **Recorded that an unvalidated field name in a stored clause is a production
+  outage class, not a typo.** `parseOptionsWhere` maps only the operator and passes the field slot
+  straight to MySQL, so an undeclared `_`-prefixed name becomes `Unknown column` → an uncaught
+  500 with an **empty body**. Live case: a draft `_isServiceClass` condition on Elite's
+  `inventory_items` view 500'd `GET /v2/items` 91 times in 5 minutes across 7 prod api2 instances
+  (2026-09-17); `_isServiceClass` was declared on no model and existed in no repo or git history.
+  Added the deploy-ordering rule (the `_underscore` `FIELD_SQL` field must be deployed **before**
+  the `dbchanges2` file that references it, because a clause is data and needs no deploy), the
+  debugging path (an unexplained `where=` field lives in `TableViews.apiWhereClause`, not the
+  frontend repo), and the open gap that api2 rejects unknown operators but not unknown fields.
+  Diagnosis only, no code changed. Prod re-verified 2026-09-29: zero `TableViews` rows across all
+  37 `Client_*` databases reference the field. (bala)
 
 - 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

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-17
+updated: 2026-09-29
 owners: [tcox, bala, rgirish]
 files:
   - dbchanges2/Client_Elite/
@@ -297,6 +297,17 @@ for the technique and the parser mechanics.
 required a `_isServiceClass` model field on `_Model_Elite_Item`; **that field does not exist and is
 not needed** — do not add one.
 
+**⚠ That earlier draft reached PRODUCTION and took `/v2/items` down.** Before the rewrite, the
+stored clause was `(Items.partNumber:excludes:SVC-,_isServiceClass:eq:0)`. `_isServiceClass` is
+declared on neither `_Model_Client_Item` nor `_Model_Elite_Item`, so the raw name went into the SQL
+and MySQL threw `Unknown column '_isServiceClass' in 'where clause'` — **91 empty-body 500s on
+`GET /v2/items` in 5 minutes across 7 prod api2 instances (2026-09-17)**. A stored clause needs no
+deploy, so it went live the moment the migration ran. Closed: `2026-09-15a` reverted the clause and
+the current one uses only `_qtyOnHand` / `_qtyAvailable`, which **are** declared `FIELD_SQL`.
+Re-verified 2026-09-29 — zero `TableViews` rows in any of the 37 prod `Client_*` databases mention
+`ServiceClass`. The general rule and the debugging path are in
+[apiWhereClause row filtering](../../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md#gotchas--known-issues).
+
 ### Why the class check replaced the `SVC-` prefix
 
 The `SVC-` prefix was an unreliable signal. Verified on **prod `Client_Elite`** (2026-09-15):
@@ -388,6 +399,15 @@ the old `SVC-` prefix check back into the clause.
   [error-reporting-issue-event](../../../2.0/apps/_underscore/features/error-reporting-issue-event.md).
 
 ## Change history
+- 2026-09-29 — **Recorded that the abandoned `_isServiceClass` draft clause actually shipped to
+  production and caused an outage**, which this doc previously reported only as "does not exist and
+  is not needed". The stored clause `(Items.partNumber:excludes:SVC-,_isServiceClass:eq:0)` put an
+  undeclared field into the SQL, giving `Unknown column '_isServiceClass' in 'where clause'` and 91
+  empty-body 500s on `GET /v2/items` in 5 minutes across 7 prod api2 instances (2026-09-17).
+  Incident is closed — `2026-09-15a` reverted the clause, the live one uses only the declared
+  `FIELD_SQL` fields `_qtyOnHand` / `_qtyAvailable`, and a 2026-09-29 sweep of all 37 prod
+  `Client_*` databases found no `TableViews` row mentioning `ServiceClass`. Diagnosis only, no code
+  changed. (bala)
 - 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,

package/package.json

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