toga-ai 1.0.349 → 1.0.351

package/knowledge/2.0/apps/api2/INDEX.md

@@ -9,6 +9,7 @@
 | [Nested-relationship writes & child matching (link vs. create)](features/nested-relationship-writes.md) | When a 2.0 API write payload (`POST`/`PUT`) contains a **nested related object** (e.g. | api2/Component/Api/V2/V2.php |
 | [POST + JSON-body args for scripted APIs](features/scripted-api-post-body-args.md) | The V2 engine can run a Record Script (scripted API) for a **POST** request, and a scripted API can receive its arguments from the **JSON request body** instead | api2/Component/Api/V2/V2.php |
 | [Surface action-state via the surface=<slug> request option (M2M-safe)](features/surface-meta-option.md) | An opt-in V2 engine request option, `surface=<slug>`, that attaches per-record UI action state (`isVisible`/`isEnabled`) to a GET response **under `meta.surface | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Surface.php |
+| [TableView row-filtering via apiWhereClause (options.where grammar, end to end)](features/tableview-apiwhereclause-row-filtering.md) | `TableViews.apiWhereClause` (TEXT, nullable) is the sanctioned, code-free way to restrict or exclude rows from a 2.0 table view. | api2/Component/Api/V2/V2.php, _underscore/Model/Client/TableView.php, toga2-supply/src/api/toga.ts |
 | [Tickets API (/v2/tickets)](features/tickets-api.md) | The generic ticket endpoint of the 2.0 REST API. | Component/Api/V2/V2.php |
 | [AWS CodePipeline Deployment via CodeConnections (GitHub → Elastic Beanstalk)](workflows/codepipeline-codeconnections-deploy.md) | 2.0 apps (`api2`, `_underscore`) are deployed through **AWS CodePipeline**. |  |
 | [New Environment Configuration & Provisioning (api2)](workflows/environment-configuration-and-provisioning.md) | What it takes for a 2.0 API environment (e.g. | api2/Config/<environment>.ini, api2/Controller/Index.php, dbchanges2/Core/2026-06-16a - DatabaseHosts for new QA QC stage demo environments.sql, _underscore/Route.php |

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

@@ -0,0 +1,115 @@
+---
+title: TableView row-filtering via apiWhereClause (options.where grammar, end to end)
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-07-15
+owners: ["bala"]
+files:
+  - api2/Component/Api/V2/V2.php
+  - _underscore/Model/Client/TableView.php
+  - toga2-supply/src/api/toga.ts
+related:
+  - ../../../clients/compass-usa/features/item-fulfillment-tracking-tableview.md
+---
+
+## Summary
+
+`TableViews.apiWhereClause` (TEXT, nullable) is the sanctioned, code-free way to restrict or
+exclude rows from a 2.0 table view. The clause is stored on the view, emitted verbatim in the
+view meta by `_underscore`, pushed into the data request's `options.where.and` by the frontend,
+and finally parsed into SQL by api2's `parseOptionsWhere`. Because api2 parses it for *every*
+data request, the same `field:operator:value` grammar governs any `options.where` filter — table
+views are just one producer of it. Use this to add a "restrict/exclude these rows" rule to a
+view with a migration and no application code.
+
+## Key files / entry points
+
+- **Emission** — `_underscore/Model/Client/TableView.php`, the `meta()` scripted API (~line 51):
+  emits `TableViews.apiWhereClause` verbatim in the view meta, and builds `join`/`ojoin` entries
+  from `TableViewJoins` (~line 631-641 of the consumer) so every table joined in the view is
+  present on the data request.
+- **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.
+
+## How it works
+
+Clause syntax: `field:operator:value`. Conditions are comma-separated, grouped with parens, and
+joined with `,AND,` / `,OR,` between conditions. The parser tracks parenthesis depth and only
+splits conditions on commas at the **top** depth.
+
+Operator tokens map to SQL as:
+
+| token | SQL |
+|-------|-----|
+| `eq` | `=` |
+| `ne` | `<>` |
+| `gt` | `>` |
+| `ge` | `>=` |
+| `lt` | `<` |
+| `le` | `<=` |
+| `like` | `LIKE` |
+| `contains` / `starts` / `ends` | wildcarded `LIKE` |
+| `excludes` | `NOT LIKE` |
+| `in` | `IN` |
+| `notin` | `NOT IN` |
+| `between` | `BETWEEN` |
+| `not` | `NOT` |
+
+The field slot accepts a **raw SQL expression**, not just a plain column — e.g.
+`YEAR(SalesOrders.dateOrder)` or `IFNULL(Items.assetTypeId,0)`. Real-world example (the FEE
+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.
+
+### Join alias rule (which table-qualified name to use)
+
+In `_underscore/Model/Client/TableView.php` (~line 89-96), the **first** occurrence of a joined
+table in a view gets the bare table name as its SQL alias (e.g. `Items`); each subsequent join to
+the same table gets a `_B`, `_C`, … suffix (counter starts at ASCII 65). So an `apiWhereClause`
+referencing `Items.<field>` only binds correctly when the view joins `Items` **exactly once**.
+Before writing a clause, confirm the target table is joined once, or qualify against the correct
+suffixed alias.
+
+## Data model
+
+- `TableViews.apiWhereClause` (TEXT, nullable) — the view-level row filter.
+- `TableViewJoins` — the view's joins; drive `options.join` / `ojoin` so any table referenced in
+  the clause is present on the data request.
+
+## Client variations
+
+None — engine behavior. A specific client's view may carry its own `apiWhereClause` value.
+
+## Gotchas / known issues
+
+- **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.
+- **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.
+- **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."
+- **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-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
+  (`_B`/`_C`) rule. No code change — mechanism discovered while building the Compass FEE-exclusion
+  migration. (bala)
+
+## Related docs
+
+- `clients/compass-usa/features/item-fulfillment-tracking-tableview.md` — the Compass fulfillment
+  view (id 12) that first used this to exclude FEE-asset-type items.
+- `clients/compass-usa/features/cost-centers.md` — notes `parseOptionsWhere` rejecting `regexp`
+  with a 500 (operator allowlist).

package/knowledge/2.0/apps/toga2-supply/INDEX.md

@@ -3,5 +3,5 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [TOGa Supply (toga2-supply) Architecture](architecture.md) | `toga2-supply` is the **React + Vite frontend** for TOGa Supply — warehouse fulfillment tooling (shipment selection, fulfill & ship against carrier APIs, NetSui | toga2-supply/src/api/toga.ts, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx |
-| [Fulfill & Ship](features/fulfill-and-ship.md) | Fulfill & Ship lets a warehouse user select sales-order line items, enter serials, pick a carrier/method, and in one action: create the Item Fulfillment records | toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/pages/EditShipment/view/components/SelectedShipmentItemsTable.tsx, toga2-supply/src/pages/EditShipment/view/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/DUMMYUPDATESHIPMENTFIELDS.json, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/tailwind.config.cjs, toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx, toga2-supply/src/components/ui/BaseInput/BaseInput.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/formatShipmentData.ts, toga2-supply/src/pages/EditShipment/types.ts, toga2-supply/src/pages/Shipments/view/ShipmentsPage.tsx, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, toga2-supply/src/pages/Shipments/types.ts, toga2-supply/src/pages/FulfilledShipments/view/FulfilledShipmentsPage.tsx, toga2-supply/src/components/ui/CardTable/CardTable.tsx, toga2-supply/src/components/ui/CardTable/types.ts, toga2-supply/src/assets/pen-line.svg, _underscore/Model/Client/ItemFulfillment.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php |
+| [Fulfill & Ship](features/fulfill-and-ship.md) | Fulfill & Ship lets a warehouse user select sales-order line items, enter serials, pick a carrier/method, and in one action: create the Item Fulfillment records | toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/pages/EditShipment/view/components/SelectedShipmentItemsTable.tsx, toga2-supply/src/pages/EditShipment/view/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/DUMMYUPDATESHIPMENTFIELDS.json, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/tailwind.config.cjs, toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx, toga2-supply/src/styles/index.scss, toga2-supply/src/components/ui/BaseInput/BaseInput.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/formatShipmentData.ts, toga2-supply/src/pages/EditShipment/types.ts, toga2-supply/src/pages/Shipments/view/ShipmentsPage.tsx, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, toga2-supply/src/pages/Shipments/types.ts, toga2-supply/src/pages/FulfilledShipments/view/FulfilledShipmentsPage.tsx, toga2-supply/src/components/ui/CardTable/CardTable.tsx, toga2-supply/src/components/ui/CardTable/types.ts, toga2-supply/src/assets/pen-line.svg, _underscore/Model/Client/ItemFulfillment.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php |
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-supply` (React + Vite) builds and deploys on **AWS Amplify**. | toga2-supply/amplify.yml, toga2-supply/.gitattributes, toga2-supply/.github/workflows/sync-stage-environments.yml, toga2-supply/.env.qc-security |

package/knowledge/2.0/apps/toga2-supply/features/fulfill-and-ship.md

@@ -18,6 +18,7 @@ files:
   - toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx
   - toga2-supply/tailwind.config.cjs
   - toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx
+  - toga2-supply/src/styles/index.scss
   - toga2-supply/src/components/ui/BaseInput/BaseInput.tsx
   - toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts
   - toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/formatShipmentData.ts
@@ -187,6 +188,27 @@ bare string** — see the gotcha below before wiring a new select field.
   (`onBlur` when `field.isCurrency`). Return modal (`ReturnShippingModal.tsx`): compact selects
   vertically centered; Carrier Account # widened to `w-[172px]` to match Carrier.
 
+### Edit Return Label modal — searchable Addressee combobox + discard guard (2026-07-15)
+
+`ReturnShippingModal.tsx`:
+- **Addressee is a searchable combobox built on a native `<input list>` + `<datalist>`** of
+  warehouse/location options — typing filters the list (Chromium does a substring "contains" match;
+  Firefox only prefix-matches) and **custom free text is still allowed**; selecting a known option
+  prefills the address via `applyWarehouse`. Prefer this native pattern over react-select when free
+  text plus suggestions are both wanted — but mind the two gotchas below.
+- **Backdrop-click discard guard.** `BaseModal` calls its `onClose` prop on backdrop click, which
+  would silently discard unsaved edits. Pass a **guarded** handler to `BaseModal`'s `onClose`
+  (`if (formMethods.formState.isDirty) return; onClose();`) so an accidental outside click can't
+  drop a dirty form, while **Cancel and the header X still call the real `onClose`** to close/discard
+  explicitly. Reuse this pattern for any BaseModal wrapping an editable form.
+
+### Shared checkbox restyled to the Figma design-system spec (2026-07-15)
+
+`BaseInput.tsx`'s checkbox now matches the Figma checkbox component: **16px** (was 20px),
+`rounded-sm`, unchecked border `navy-300`, checked fill `supply-blue-400` (`#3F5DCA`, the primary),
+12px check glyph. This is the **shared** checkbox, so the change applies **app-wide**, not just to
+the shipment forms — audit other consumers when touching it.
+
 ## Planned direction — "Fulfill & Ship" from an existing Item Fulfillment (future, Eric)
 
 A **third entry mode** is planned (distinct from Select-Items-create and the pencil-edit): a
@@ -221,7 +243,27 @@ the call 403s and returns no label.
 
 ## Gotchas / known issues
 
-- **⚠ Tailwind does NOT scan the field-config JSON — a class used ONLY in `viewModel/FIELDS/*.json`
+- **⚠ Native `<datalist>` renders its OWN dropdown arrow, un-hideable by Tailwind.** An
+  `<input list>` combobox (the Edit Return Label Addressee) shows a **second dark arrow** (the
+  webkit calendar-picker indicator) that a Tailwind arbitrary variant can't reliably hide. Kill it
+  with a **real global CSS rule** in the source stylesheet
+  `src/styles/index.scss` (imported by `main.tsx`):
+  `input[list]::-webkit-calendar-picker-indicator { display: none !important; }`.
+  **Edit `index.scss`, NOT `index.css`** — `index.css` is compiled output and will be overwritten.
+  Also set **`autoComplete="off"`** on the input or the browser's address-autofill popup
+  ("Saved data / Manage personal info") overlaps and fights the datalist.
+- **⚠ A `className` template literal must keep the trailing space before `${...}`.** `border ${cond
+  ? a : b}` is correct; `border${cond ? a : b}` concatenates into an invalid single class
+  (e.g. `borderborder-navy-300`) and the utility silently no-ops. Concrete failure: the `BaseInput`
+  checkbox's unchecked border disappeared because the space was dropped. Watch this whenever
+  conditional classes are appended to a static base class.
+- **⚠ `justify-between` + `clamp()` gaps are frozen when the container is a FIXED width.** The Update
+  Info field row uses `gap-x-[clamp(2px,1vw,50px)]` with `justify-between`, but the card was a fixed
+  `w-[1820px]`, so `justify-between` distributed columns across a constant width and the gaps never
+  changed on resize. Fix: make the card `w-full max-w-[1820px]` and the form section `w-full` so the
+  width tracks the viewport and the clamp'd gaps grow/shrink with it. Note `justify-between` does
+  **not** cap the max gap at 50px on very wide screens — the `clamp` only *floors* at 2px; the max
+  applies until columns are pushed to the edges. (`EditShipmentPage.tsx`.) — a class used ONLY in `viewModel/FIELDS/*.json`
   is silently inert.** The config-driven forms author Tailwind utility classes inside the field JSON
   (e.g. `DUMMYUPDATESHIPMENTFIELDS.json`), but `tailwind.config.cjs` `content` globs only scan
   `./src/**/*.{js,ts,jsx,tsx}` (+ `index.html` + toga-blox dist) — **not `.json`**. So a class used
@@ -417,6 +459,18 @@ not the base `_Model_Client_ItemFulfillment`. Tested with GroWrk; UPS support wa
 for Compass and is not yet in prod.
 
 ## Change history
+- 2026-07-15 — TRUE-79191: made the Edit Return Label **Addressee a searchable combobox** (native
+  `<input list>` + `<datalist>`, filters + allows custom text, prefills via `applyWarehouse`); added a
+  **backdrop-click discard guard** (guarded `BaseModal onClose` on `formState.isDirty`); restyled the
+  **shared `BaseInput` checkbox** to the Figma spec (16px, navy-300 border, `supply-blue-400` fill,
+  app-wide). Documented four durable gotchas: native `<datalist>`'s un-hideable arrow (hide via a
+  real global rule in `src/styles/index.scss`, not the compiled `index.css`) + `autoComplete="off"`
+  to stop autofill overlap; the `className` **trailing-space-before-`${...}`** footgun (dropped space
+  → invalid concatenated class → silent no-op, killed the checkbox border); and `justify-between` +
+  `clamp()` **gaps frozen by a fixed-width card** (fix: `w-full max-w-[1820px]` so width tracks the
+  viewport). Remaining Figma polish (5-col address grid, Signature default object, declared-cost
+  2-decimal rehydrate, Clear All wiring, residential alignment, footer/divider spacing) was cosmetic
+  — no doc change. (mhammontree)
 - 2026-07-15 — TRUE-79191: unified the **dropdown chevron glyph** across the compact selects — added a
   `CompactDropdownIndicator` (FA `chevronDown`) to `BaseInput` and wired it into both react-select
   `components` blocks **only when `compact` is true**, so the react-select caret matches the native

package/knowledge/INDEX.md

@@ -19,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **_underscore** (_Underscore) _(framework core)_ — 32 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 30 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 10 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 11 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)

package/knowledge/clients/compass-usa/INDEX.md

@@ -4,7 +4,7 @@
 |-----|-----------|---------|-------|
 | [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF) on the upstream SalesOrder. | _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Model/Compass/PurchaseOrder.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql, dbchanges2/Client_Compass/2026-06-15b - BackfillSA132781ItemFulfillmentTracking.sql, dbchanges2/Client_Compass/2026-06-16 - CleanupSA132763CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16b - CleanupSA132743CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16c - BackfillSA132763C40QYUCTracking.sql, dbchanges2/Client_Compass/2026-06-18a - CleanupSA132898DuplicateTracking.sql, dbchanges2/Client_Compass/2026-06-18b - CleanupSA132881DuplicateTracking.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql |
 | [Cost Centers — Unit Locations, numeric-only policy](features/cost-centers.md) | 2.0 | A Compass "cost center" — the value a user picks in commerce and that lands on an order — is **not** a `CostCenters` row. | toga2-commerce/src/pages/Cart/api/CartApi.ts, worker1.5/crons/toga2/compass/import_locations.php, _underscore/Model/Compass/SalesOrder.php, api2/Component/Api/V2/V2.php, dbchanges2/Client_Compass/2026-07-06 - RemoveNonNumericCostCenters.sql |
-| [Compass: Item-Fulfillment TableViews (for-sales-order-items & for-sales-orders, tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | Two sibling Compass TableViews in `Client_Compass` display fulfilled items in toga2-supply, both driven by `TableViews` / `TableViewJoins` / `TableViewFields` c | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql, dbchanges2/Client_Compass/2026-06-11 - ItemFulfillmentsForSalesOrdersTableView.sql, dbchanges2/Client_Compass/2026-06-15a - FixItemFulfillmentTrackingNumberJoins.sql |
+| [Compass: Item-Fulfillment TableViews (for-sales-order-items & for-sales-orders, tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | Two sibling Compass TableViews in `Client_Compass` display fulfilled items in toga2-supply, both driven by `TableViews` / `TableViewJoins` / `TableViewFields` c | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql, dbchanges2/Client_Compass/2026-06-11 - ItemFulfillmentsForSalesOrdersTableView.sql, dbchanges2/Client_Compass/2026-06-15a - FixItemFulfillmentTrackingNumberJoins.sql, dbchanges2/Client/2026-07-15a - ExcludeFeeItemsFromItemFulfillmentsForSalesOrdersView.sql |
 | [Compass MITS PO → SO Item Linking](features/mits-po-to-so-item-linking.md) | 2.0 | MITS sends Compass inbound Purchase Orders (`POST /v2/purchase-orders`) against a Sales Order (`mitsSalesOrder`). | _underscore/Model/Compass/PurchaseOrder.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |
 | [Compass MITS PO Transmission to Vendors](features/mits-po-transmission-to-vendors.md) | 2.0 | The 1.0 worker cron `2_transmit_mits_purchase_orders_to_vendors.php` transmits Compass PurchaseOrders to their vendors (Office Depot, Strategic Systems, Compass | worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, worker/crons/toga2/compasscanada/workflow/2_transmit_mits_purchase_orders_to_vendors.php, library/app/client/compass.php |
 | [Compass MR/MA Order Auto-Approval & Status Gate](features/mr-ma-order-approval-and-status.md) | 2.0 | Compass **MR** and **MA** sales orders are system-generated from the MITS / Office Depot EDI pipeline (they do not originate as user-entered SA orders) and must | _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/PurchaseOrder.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |

package/knowledge/clients/compass-usa/features/item-fulfillment-tracking-tableview.md

@@ -5,14 +5,16 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-06-15
-owners: ["jcardinal"]
+updated: 2026-07-15
+owners: ["jcardinal", "bala"]
 files:
   - dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql
   - dbchanges2/Client_Compass/2026-06-11 - ItemFulfillmentsForSalesOrdersTableView.sql
   - dbchanges2/Client_Compass/2026-06-15a - FixItemFulfillmentTrackingNumberJoins.sql
+  - dbchanges2/Client/2026-07-15a - ExcludeFeeItemsFromItemFulfillmentsForSalesOrdersView.sql
 related:
   - ../../../2.0/apps/_underscore/features/tracking-number-bridges.md
+  - ../../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md
 ---
 
 ## Summary
@@ -93,14 +95,30 @@ returnTrackingNumberId. Superseded unit-level keys: 2183 IFIU-bridge.itemFulfill
 - With null `joinOnTableViewJoinId`, the engine resolves a join's parent table by the `recordId` of
   `parentRecordFieldId` — this only works because each record appears once in the graph. Reusing a
   record twice in one view would require an explicit `joinOnTableViewJoinId`.
+- **FEE-item exclusion (view 12) is filtered via `apiWhereClause`, and "asset type" is a nullable
+  FK — not a string.** `Items.assetTypeId` is a nullable FK to `AssetTypes(id, uuid, name)`; the
+  id for a given name (e.g. `FEE`) **differs per client** (Compass: `FEE` = id 3, 62 items). About
+  30% of `Items` rows have a **NULL** `assetTypeId` (Compass: 227,685 of ~269,980 fulfilled-item
+  rows in this view), so any exclusion **must be NULL-safe** — a plain `assetTypeId:ne:<id>` would
+  silently drop every NULL row. The migration uses `(IFNULL(Items.assetTypeId,0):ne:<FEE id>)` with
+  the FEE id resolved per client DB via `(SELECT id FROM AssetTypes WHERE name='FEE' ...)`. See the
+  shared `apiWhereClause` mechanism doc. The `apiWhereClause` binds `Items.assetTypeId` correctly
+  only because view 12 joins `Items` exactly once (the join-alias rule).
+- **The FEE-exclusion migration is team-wide, not Compass-only.** It lives in the `dbchanges2/Client/`
+  fan-out folder, so it runs against **every** client DB, guarded to fire only where the view exists,
+  a `FEE` asset type exists, and `Items` is joined exactly once. It composes idempotently onto any
+  existing `apiWhereClause` (a CASE skips if `%assetTypeId%` is already present). Verified read-only
+  on prod + dev-sandbox that it excludes only FEE rows and keeps all NULL-assetType rows.
 
 ## Client variations
 Compass-only. The underlying bridge model is shared (see the _underscore feature doc).
 
 ## Change history
+- 2026-07-15 — Excluded FEE-asset-type items from view 12 (`item-fulfillments-for-sales-orders`) via a NULL-safe `apiWhereClause` `(IFNULL(Items.assetTypeId,0):ne:<FEE id>)`, FEE id resolved per client DB. Migration `2026-07-15a` in `dbchanges2/Client/` (fans out to all clients, idempotent, guarded). Verified read-only on prod + dev-sandbox. (bala)
 - 2026-06-15 — Re-pointed tracking from the unit-level bridge (319) to the item-level bridge `ItemFulfillmentItems_TrackingNumbers` (318) in views 12 & 13; fixes blank item-level tracking on non-serialized lines (e.g. SO MR243437). Migration `2026-06-15a`. (jcardinal)
 - 2026-06-11 — Re-rooted `item-fulfillments-for-sales-orders` (id 12) from Units to ItemFulfillmentItems with OUTER unit/tracking chain; fixes 0-records on orders lacking unit breakdown (e.g. SA132740). (jcardinal)
 - 2026-06-10 — Re-rooted `item-fulfillments-for-sales-order-items` (id 13) and moved tracking to the bridge join. (jcardinal)
 
 ## Related docs
 - 2.0 _underscore: Tracking-Number Bridge Migration.
+- 2.0 api2: TableView row-filtering via apiWhereClause (the mechanism used for the FEE exclusion).

package/package.json

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