toga-ai 1.0.727 → 1.0.728

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-07-15
+updated: 2026-09-01
 owners: ["bala"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -14,6 +14,7 @@ files:
   - toga2-supply/src/api/toga.ts
 related:
   - ../../../clients/compass-usa/features/item-fulfillment-tracking-tableview.md
+  - ../../../clients/compass-usa/features/item-catalogs-and-duplicate-items.md
   - tableview-field-metadata.md
 ---
 
@@ -36,8 +37,9 @@ view with a migration and no application code.
 - **Consumption** — `toga2-supply/src/api/toga.ts` (~line 943-951): pushes the `apiWhereClause`
   literal string into `options.where.and`, and (~line 631-641) builds `options.join` / `ojoin`
   from the view's `TableViewJoins`.
-- **Parsing** — `api2/Component/Api/V2/V2.php::parseOptionsWhere` (~line 7574-7773): turns the
-  clause string into SQL.
+- **Parsing** — `api2/Component/Api/V2/V2.php::parseOptionsWhere` (~line 8200-8390, re-located
+  2026-09-01; it was ~7574 when this doc was first written, so search for the function name rather
+  than trusting the line number): turns the clause string into SQL.
 
 ## How it works
 
@@ -68,6 +70,22 @@ The field slot accepts a **raw SQL expression**, not just a plain column — e.g
 exclusion on the Compass fulfillment view): `(IFNULL(Items.assetTypeId,0):ne:<FEE id>)` — the
 `IFNULL(...,0)` keeps rows with a NULL FK from being silently dropped.
 
+### A single-condition clause is wrapped in parens too
+
+`parseOptionsWhere` **strips one leading `(` and one trailing `)` from the whole clause before it
+scans for top-depth commas** (V2.php ~line 8222-8229). Those outer parens are the group wrapper,
+not part of the first condition, so the house form for a one-condition filter is:
+
+```
+(Items.catalogId:eq:1)
+```
+
+The wrapper comes off first, leaving `Items.catalogId:eq:1`, which is then read as a plain
+condition — it is never mistaken for a nested group needing recursion. Write the parens; they match
+the existing Compass convention and the stored clauses stay uniform whether they hold one condition
+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.)
+
 ### Join alias rule (which table-qualified name to use)
 
 In `_underscore/Model/Client/TableView.php` (~line 89-96), the **first** occurrence of a joined
@@ -77,6 +95,19 @@ referencing `Items.<field>` only binds correctly when the view joins `Items` **e
 Before writing a clause, confirm the target table is joined once, or qualify against the correct
 suffixed alias.
 
+**A view's base record is not a join, so it never gets a suffix.** Worked example — the shared
+`items` view (`TableViews.slug = 'items'`, `id 9`, `recordId 21` = `_Model_Client_Item`, route
+`items`; the same shape in `Client_Compass`, `Client_CompassCanada` and `Client_Quad`). Its four
+`TableViewJoins` are `joinRecordId` **20** Manufacturers, **33** ItemTypes, **32** AssetTypes and
+**34** ItemCategories, all INNER. `Items` appears only as the base record and is never re-joined,
+so the bare `Items.` qualifier is correct and there is no `_B`/`_C` to worry about. Check this the
+same way on any view before writing a clause: list the view's `TableViewJoins` and count how many
+resolve to the table you want to filter.
+
+Two schema notes for anyone writing the migration: `TableViews` has **no `name` or `tableName`
+column** in these client schemas — identify a view by its `slug` (UNIQUE) plus `recordId`, which is
+what makes `WHERE slug = 'items'` a safe, id-agnostic target across tenants.
+
 ## Data model
 
 - `TableViews.apiWhereClause` (TEXT, nullable) — the view-level row filter.
@@ -91,6 +122,8 @@ None — engine behavior. A specific client's view may carry its own `apiWhereCl
 
 - **Comma inside a function is safe.** The parser only splits conditions on top-depth commas, so
   a comma inside `IFNULL(x,0)` or `IN(...)` does not break the clause.
+- **A one-condition clause still needs its outer parens** — they are stripped before parsing, so
+  `(Field:eq:value)` and `Field:eq:value` behave identically; use the wrapped form for consistency.
 - **An expression field must NOT start with `(`.** A condition that starts with `(` is treated by
   the parser as a nested group and recursed into — so wrap an expression field in a function that
   starts with a letter (e.g. `IFNULL(...)`), never a bare parenthesized expression.
@@ -102,6 +135,15 @@ None — engine behavior. A specific client's view may carry its own `apiWhereCl
 
 ## Change history
 
+- 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).
+  Added a worked alias-verification example on the shared `items` view (id 9, recordId 21, four
+  INNER `TableViewJoins` 20/33/32/34, `Items` only as base record → bare `Items.` qualifier), noted
+  that `TableViews` carries no `name`/`tableName` column so `slug` is the id-agnostic target, and
+  re-pointed `parseOptionsWhere` at its current location (~8200, was ~7574). No code change —
+  verified while writing the catalog-1 filter migration for the `items` view in `Client_Compass`,
+  `Client_CompassCanada` and `Client_Quad`. (bala)
 - 2026-07-15 — Documented the end-to-end `apiWhereClause` row-filter mechanism (emission →
   consumption → `parseOptionsWhere` grammar), the operator→SQL table, the raw-expression field
   slot, the leading-paren / top-depth-comma parser behavior, and the `_underscore` join-alias

package/knowledge/clients/compass-canada/profile.md

@@ -196,4 +196,12 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   numbers — because it does **not** use NetSuite, so it never hit the inventory-adjustment
   dupe-item bug that fed the merge. The catalog-fold damage and reversal were Compass USA only.
   See [Compass USA catalog-fold reversal](../compass-usa/workflows/catalog-fold-reversal.md).
+- **Items listing being filtered to catalog 1 (written 2026-09-01, NOT yet applied).** A migration
+  sets `TableViews.apiWhereClause = '(Items.catalogId:eq:1)'` on `Client_CompassCanada`'s shared
+  `items` view (`slug = 'items'`, id 9, recordId 21), alongside the same change in `Client_Compass`
+  and `Client_Quad`. **Canada is the harmless case today** — Canada has a **single catalog**
+  ("compass", see the bullet above), so every `Client_CompassCanada.Items` row is already catalog 1 and so the filter changes nothing visible now; it only pins the listing so a
+  future non-catalog-1 item (e.g. anything a NetSuite-style sync creates) would silently not appear.
+  Mechanism: [TableView apiWhereClause row-filtering](../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md);
+  catalog background: [Compass item catalogs](../compass-usa/features/item-catalogs-and-duplicate-items.md).
 - Related: [Compass USA](../compass-usa/profile.md).

package/knowledge/clients/compass-usa/features/item-catalogs-and-duplicate-items.md

@@ -17,6 +17,7 @@ files:
   - worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php
 related:
   - odp-edi-850-item-resolution.md
+  - ../../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md
   - mits-po-to-so-item-linking.md
   - mits-sales-order-transmission-alerting.md
   - isfulfillable-data-quality-and-type-rule.md
@@ -132,6 +133,32 @@ Plus `-1` / `-2` suffixed copies: items **2431, 2432, 2443, 2653**.
   (e.g. the `#B1H` / `-S` variant forms above) or genuinely-shared ones before treating table-wide
   `partNumber` uniqueness as settled.
 
+## Filtering by catalog: fine for *display*, never for *resolution*
+
+The blanket rule below ("never scope a Compass item lookup to one catalog") is about **resolving a
+part number to a record** — order import, PO→SO linking, vendor-item matching. It does **not** mean
+a catalog filter is banned everywhere. A **listing** is the legitimate exception: showing a user
+only the customer-facing Compass catalog is a product decision, and nothing downstream re-resolves
+off that list.
+
+**In flight as of 2026-09-01 (SQL written, NOT yet applied):** the shared TOGa Supply `items` table
+view (`TableViews.slug = 'items'`, `id 9`, `recordId 21`) is being restricted to catalog 1 by
+setting `TableViews.apiWhereClause = '(Items.catalogId:eq:1)'` — one `UPDATE … WHERE slug = 'items'`
+per schema, in `Client_Compass`, `Client_CompassCanada` **and** `Client_Quad` (the same view exists
+with the same id/recordId in all three). No application code changes; the mechanism is
+[TableView row-filtering via apiWhereClause](../../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md).
+The migration was written as a loose `items_tableview_catalog_filter_2026-09-01.sql` in the
+workspace root and handed to a developer to run (the DB tooling is read-only) — it still needs to
+land in `dbchanges2/Client_<schema>/` under the mandatory `YYYY-MM-DD<letter> - Name.sql` filename
+before it is a real change-set.
+
+**Open decision on the clause, and it is the NULL question again.** `Items.catalogId` is nullable in
+all three schemas, so a bare `:eq:1` silently drops the NULL-catalog items (a real, non-trivial
+population here — see the gotcha below, and it is proportionally much larger in `Client_Quad`). If
+those items must stay visible in the listing, the clause has to be
+`(IFNULL(Items.catalogId,1):eq:1)` instead. Decide before applying; the two forms are not
+interchangeable.
+
 ## "Who changed this part number?" — the audit trail says nobody
 
 The reflex answer to a part number that looks edited is to hunt for the person who edited it. For
@@ -151,9 +178,10 @@ children" rule:
 
 ## Gotchas
 
-- **⚠ Never scope a Compass item lookup to one catalog** unless you have proved the item can only
-  come from that source. The correct default is `Items.partNumber IN (...)` with **no** catalog
-  condition, and then reference the resolved record **by `uuid`**. **The catalog filter never buys
+- **⚠ Never scope a Compass item *lookup* to one catalog** unless you have proved the item can only
+  come from that source. (A read-only **listing** filter is the one sanctioned exception — see
+  [Filtering by catalog](#filtering-by-catalog-fine-for-display-never-for-resolution) above.) The
+  correct default is `Items.partNumber IN (...)` with **no** catalog condition, and then reference the resolved record **by `uuid`**. **The catalog filter never buys
   uniqueness on Compass** — `Items.partNumber` is unique across the whole table (re-verified prod
   2026-09-01) — so every catalog condition is pure downside.
 - **⚠ The 2.0 side hardcodes the OTHER catalog, and it broke MR purchase orders.**
@@ -193,6 +221,14 @@ children" rule:
   **unresolved tension**: that reversal folded/restored 199 catalog-1 items by `UPPER(partNumber)`,
   which implies shared cross-catalog part numbers pre-merge and does not square with the same-day
   "partNumber is unique table-wide" verification — needs a prod re-check. (jcardinal)
+- 2026-09-01 — Split the catalog-filter rule into **display vs. resolution**: the "never scope to one
+  catalog" ban covers part-number *resolution*, while a read-only *listing* filter is sanctioned.
+  Recorded the in-flight (written, **not yet applied**) change setting
+  `TableViews.apiWhereClause = '(Items.catalogId:eq:1)'` on the shared `items` view
+  (`slug = 'items'`, id 9, recordId 21) in `Client_Compass`, `Client_CompassCanada` and
+  `Client_Quad`, and the open decision it carries: `Items.catalogId` is nullable, so bare `:eq:1`
+  hides NULL-catalog items and `IFNULL(Items.catalogId,1):eq:1` is the alternative. Migration still
+  needs moving into `dbchanges2/Client_<schema>/`. (bala)
 - 2026-09-01 — Recorded a **second, independent victim of the same catalog-scoping trap, on the 2.0
   side**: `_Model_Compass_PurchaseOrder::handleMrOrder` references MR sales-order items with a
   hardcoded `COMPASS_CATALOG_UUID` (`961dbcbc…` = catalog **1**), which is the mirror image of the

package/knowledge/clients/quad/profile.md

@@ -142,4 +142,16 @@ Client-specific DB change-sets live in `dbchanges2/Client_Quad/`.
   Quad's **storefront only** (not orders/transmit), and Quad was the **only other client besides
   Compass** that needed a reversal. See
   [Quad catalog-fold reversal](./workflows/catalog-fold-reversal.md).
+- **Items listing being filtered to catalog 1 (written 2026-09-01, NOT yet applied) — verify the
+  intent for Quad first.** A migration sets `TableViews.apiWhereClause = '(Items.catalogId:eq:1)'`
+  on `Client_Quad`'s shared `items` view (`slug = 'items'`, id 9, recordId 21); the same one-line
+  change is going to `Client_Compass` and `Client_CompassCanada`. Read it against the bullet above:
+  for Quad, catalog 1 is the **storefront (Etilize)** catalog and catalog 2 is the **procurement
+  (Agilant/NetSuite)** catalog that Quad's storefront orders actually sit on, so `:eq:1` hides the
+  procurement half of `Client_Quad.Items` from the Supply items listing — a much bigger cut than the
+  equivalent change on Compass, and a majority of Quad's items. `Items.catalogId` is also nullable
+  here and a bare `:eq:1` drops those rows too; `IFNULL(Items.catalogId,1):eq:1` recovers the NULLs
+  but not catalog 2. Mechanism:
+  [TableView apiWhereClause row-filtering](../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md);
+  catalog background: [Compass item catalogs](../compass-usa/features/item-catalogs-and-duplicate-items.md).
 - This profile is a starting point; expand as more Quad-specific behavior is captured.

package/package.json

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