toga-ai 1.0.666 → 1.0.667

package/knowledge/2.0/apps/api2/features/v2-rest-query-contract.md

@@ -6,11 +6,12 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-21
+updated: 2026-08-27
 owners: [tcox, bala, apeterson]
 files:
   - api2/Component/Api/V2/V2.php
 related:
+  - ../../toga2-commerce/features/bundle-item-visibility-and-selectability.md
   - ../architecture.md
   - v2-api-error-codes.md
   - tableview-apiwhereclause-row-filtering.md
@@ -109,8 +110,11 @@ switching that tenant to the join endpoint.
 
 ### ⚠ A `where` clause on a single-uuid READ is silently IGNORED
 
-**`GET /v2/items/{uuid}` does not filter.** The by-uuid READ path loads the record through
-`locateRecord()`, which resolves by uuid and **never reads `httpOptions['where']`**. The parameter
+**`GET /v2/items/{uuid}` does not filter.** A route with a uuid (`count($routePair) == 2`) is
+classified **`ACTION__READ`**, not `ACTION__LIST` (`V2.php:3022-3026`). The `ACTION__READ` branch
+runs from `V2.php:4399` to the `ACTION__DELETE` case (~`V2.php:5478`) and contains **no `where`
+handling whatsoever** — `where` is parsed, then applied only in the `ACTION__LIST` branch
+(`V2.php:3526`) and in the uuid-less DELETE/PUT lookup (~`V2.php:5529`). The parameter
 is accepted, produces no error, and has no effect — so a caller that adds
 `where=(Items.isActive:eq:1)` to a single-uuid GET gets the record back **regardless of the
 filter** and believes it has been gated.
@@ -127,6 +131,17 @@ rest of the code expects — a `null` there is then a truthful *"missing or filt
 example: [TOGa Commerce inactive-item purchase
 gating](../../toga2-commerce/features/inactive-item-purchase-gating.md).
 
+### ⚠ `where` NEVER prunes a nested child array — not even on LIST
+
+`buildWhereExpressionsFromOptions` is invoked with `defaultTable: $modelName::TABLE`, the **root**
+model. A `where` therefore constrains **which root rows return**; the nested one-to-many arrays are
+built afterwards by `getFullModelData()`, which the `where` never touches. **"Filter the nested
+array with `where`" is not a capability the V2 engine has** — at any depth, on any route. To reduce
+a child collection you must either query the child route directly (with the parent FK in the
+`where`) or filter client-side. Worked example:
+[bundle item visibility & selectability](../../toga2-commerce/features/bundle-item-visibility-and-selectability.md),
+where a bundle-item `isActive` filter was inert for this reason *and* the uuid-READ reason above.
+
 This is the mirror image of the LIST → READ flip below: there, an unrecognized param moves you onto
 the READ path and you get a loud 404; here, a **recognized** param is simply inert on that path and
 you get a quiet wrong answer.
@@ -164,7 +179,11 @@ where=(field:op:value,LOGIC,field:op:value,(nested,OR,nested))
   `Contacts.uuid` with no read grant on `Contacts`, as long as you never **select** a
   `Contacts.*` field. Useful when you have a child grant but not the parent's fields.
 - **Referencing a table in `where` that you did not `join`** produces invalid SQL, which is
-  uncaught → **`EO-1` 500**.
+  uncaught → **`EO-1` 500**. The field string is passed through **verbatim**: `V2.php:6959-6962`
+  prepends the default table only when the field contains no `.`, and no auto-join is ever generated
+  for an arbitrary table prefix (joins come only from explicit `join`/`ojoin` and `SPECIAL_FIELDS`).
+  So a **typo'd table prefix is neither rejected nor reported** — it reaches SQL as an unknown
+  column.
 - **Nested route `/contacts/{uuid}/contact-attempts`** auto-filters by the child's FK
   (discovered by **model class**, not field name) and requires **record-level READ on the
   parent** but **no field grant** on it.
@@ -215,6 +234,17 @@ where=(field:op:value,LOGIC,field:op:value,(nested,OR,nested))
   invisible; re-request with `fields=` to force `EZ-2` and see the denied list.
 
 ## Change history
+- 2026-08-27 — Pinned the **mechanism** behind the silently-ignored uuid-READ `where` to exact code:
+  a uuid'd route is classified `ACTION__READ` (`V2.php:3022-3026`) and that branch
+  (`V2.php:4399` → ~`5478`) has **no `where` handling at all**; `where` is applied only in
+  `ACTION__LIST` (`V2.php:3526`) and the uuid-less DELETE/PUT lookup (~`V2.php:5529`). Added two
+  further limits found in the same read: **`where` never prunes a nested child array** (it is built
+  with `defaultTable = <root>::TABLE`, and nested collections come from `getFullModelData()`, which
+  the `where` never touches — so nested filtering is not a V2 capability on any route), and a
+  `where` field with an **unknown table prefix passes into SQL verbatim** (`V2.php:6959-6962` only
+  prepends the default table when there is no `.`; no auto-join is generated), so a typo'd prefix is
+  never reported. Found while investigating unfiltered bundle items on a Compass USA order.
+  (apeterson)
 - 2026-08-21 — Documented that **`join`/`ojoin` drive the WHERE/filter, not the response shape**:
   output nesting comes from FK relationships + requested `fields` (`getFullModelData()`), and an
   aliased `ojoin` column never becomes a readable output field. Worked example: Compass's

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

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [TOGa Commerce (toga2-commerce / commerce2-react) Architecture](architecture.md) | `toga2-commerce` (npm package name **`commerce2-react`**, product name **TOGa Commerce**) is the customer-facing **B2B commerce storefront** of the 2.0 platform | src/main.tsx, src/App.tsx, src/routes.tsx, src/contexts/AuthContext.tsx, src/contexts/helpers/getLoginSettings.ts, src/api/axiosInstance.ts, src/stores/, src/themeConfig/ThemeContext.tsx, src/fieldsConfig/index.ts, src/hooks/useAssignClientFields.ts, vite.config.ts, package.json |
+| [Bundle item visibility & selectability (the three flags, and why they are enforced nowhere but the client)](features/bundle-item-visibility-and-selectability.md) | Which components of a kit a shopper can see and choose is decided **entirely in the browser**. | toga2-commerce/src/pages/BundleView/api/BundleApi.tsx, toga2-commerce/src/pages/BundleView/helpers/formatOriginalBundleData.ts, toga2-commerce/src/pages/BundleView/helpers/formatBundleToAddToCart.ts, toga2-commerce/src/pages/BundleView/hooks/useBundleEditFromLocalStorage.ts, toga2-commerce/src/stores/useBundleBuilderZu.ts, _underscore/Model/Client/BundleItem.php, _underscore/Model/Client/SalesOrderItem.php, api2/Component/Api/V2/V2.php |
 | [Cart Bundle Submission & the bundleUuid Identity Contract](features/cart-bundle-submission-and-identity.md) | How cart **bundles** (kits) are turned into `SalesOrderItems` when a cart is submitted or an existing order is edited, and the **identity-field contract** every | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts, src/utils/formatSalesOrderBundlesFromApi.ts, src/stores/useCartStoreZu.ts, src/pages/OrderDetails/helpers/formatSalesOrderDataFromLocalStorage.ts, src/pages/OrderDetails/view/components/OrderItems.tsx |
 | [Cart Notification Emails — duplicate prevention](features/cart-notification-emails.md) | On the cart "Notifications" section a user can add CC email addresses to an order. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/stores/useEmailOptionsStore.ts, src/stores/useCartSalesQuoteZu.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts |
 | [Cart Order-Total & Shipping Computation](features/cart-order-total-computation.md) | The Cart summary section (subtotal / shipping / tax / total) is **data-driven** from `cartData`. | toga2-commerce/src/pages/Cart/viewModel/useCartViewModel.ts, toga2-commerce/src/pages/Cart/CartPage.tsx, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/api/CartApi.ts |

package/knowledge/2.0/apps/toga2-commerce/features/bundle-item-visibility-and-selectability.md

@@ -0,0 +1,162 @@
+---
+title: Bundle item visibility & selectability (the three flags, and why they are enforced nowhere but the client)
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-08-27
+owners: ["apeterson"]
+files:
+  - toga2-commerce/src/pages/BundleView/api/BundleApi.tsx
+  - toga2-commerce/src/pages/BundleView/helpers/formatOriginalBundleData.ts
+  - toga2-commerce/src/pages/BundleView/helpers/formatBundleToAddToCart.ts
+  - toga2-commerce/src/pages/BundleView/hooks/useBundleEditFromLocalStorage.ts
+  - toga2-commerce/src/stores/useBundleBuilderZu.ts
+  - _underscore/Model/Client/BundleItem.php
+  - _underscore/Model/Client/SalesOrderItem.php
+  - api2/Component/Api/V2/V2.php
+related:
+  - ./cart-bundle-submission-and-identity.md
+  - ./inactive-item-purchase-gating.md
+  - ../architecture.md
+  - ../../api2/features/v2-rest-query-contract.md
+  - ../../api2/features/api-payload-interceptors.md
+  - ../../../clients/compass-usa/profile.md
+---
+
+## Summary
+
+Which components of a kit a shopper can see and choose is decided **entirely in the browser**.
+Investigated 2026-08-27 while tracing how part number `S24D402GAN` reached Compass USA order
+`SA136441` (bundle 189, "LEVY - HP ZBOOK 8"). Findings are **platform-wide, not tenant-specific** —
+no `_Model_<Client>` override participates in any of these paths.
+
+Three facts, in order of importance:
+
+1. **The server-side `isActive` filter on the bundle fetch has never executed.** It is inert for
+   three independent reasons (below), so bundle items arrive at the client **completely
+   unfiltered**.
+2. **`Client.BundleItems`' three flags mean different things depending on the row type**
+   (plain item vs. fee vs. child bundle), so no uniform flag filter can express "selectable."
+3. **Nothing on the backend validates that a posted `salesOrderItems[].bundleItem` is currently
+   selectable**, so any direct API caller can post any bundleItem uuid.
+
+## The flag conventions (non-obvious — the flag names lie)
+
+`Client.BundleItems` carries `isActive`, `isRequired`, `isVisible`. Their meaning varies **by row
+type**:
+
+| Row type | isVisible | isRequired | isActive | What it actually means |
+|---|---|---|---|---|
+| Plain component | true | either | true | shown, optionally selectable |
+| **FEE** | **false** | **true** | true | *not shown, but mandatory* — must be on the order or it cannot be placed |
+| **Child bundle** (nested kit) | true | false | **false** | intentionally inactive rows; `isActive = false` does **not** mean disabled here |
+
+So `isVisible = false` does not mean "not orderable", and `isActive = false` does not mean
+"disabled". **Any selectability filter must branch on row type first.** This is what makes the
+client-side carve-outs below necessary rather than accidental.
+
+## How it works
+
+### The dead `where` clause on the bundle fetch
+
+`src/pages/BundleView/api/BundleApi.tsx` — both `fetchSingleBundleData` (~L81-83) and
+`fetchBundleImages` (~L125-127) send, against `GET /bundles/{uuid}`:
+
+```
+where: { and: [ { "BundlesItems.isActive": { "=": "true" } } ] }
+```
+
+Three independent reasons it does nothing:
+
+- **(a) It is a uuid'd GET.** The V2 `ACTION__READ` branch contains no `where` handling at all —
+  see [V2 REST query contract](../../api2/features/v2-rest-query-contract.md).
+- **(b) Even on the LIST route it would filter the wrong thing.** `where` constrains which **root**
+  rows return; it never prunes a nested one-to-many array. Nested children are serialized by
+  `getFullModelData()`, which the `where` never touches.
+- **(c) The table name is a typo.** The model declares `TABLE = 'BundleItems'`
+  (`_underscore/Model/Client/BundleItem.php:6`); the query says `BundlesItems` (extra `s`).
+
+### Client-side filtering, and its two deliberate carve-outs
+
+`src/pages/BundleView/helpers/formatOriginalBundleData.ts`:
+
+- **The correct filter is `visibleItems`** (L11-13): `isVisible === true && isActive`.
+- **CARVE-OUT A — fees (L81).** Reads the **raw** `bundlesDataOriginal.bundleItems` and filters only
+  `assetType.name === "FEE" && isRequired && isActive` — **no `isVisible` check**. Everything
+  matching is then force-added to the order as `updatedFees`
+  (`formatBundleToAddToCart.ts:32-44`). The user never sees it and cannot deselect it. **Any item
+  mis-tagged with assetType `FEE` is therefore ordered silently.**
+- **CARVE-OUT B — child bundles (L29).** Reads the **raw** array and filters **only** on
+  `!!bundleItem?.childBundle` — all three flags ignored.
+
+These two are the only fresh-page-load paths by which a non-selectable bundle item can reach an
+order. Both are unguarded.
+
+### No server-side enforcement anywhere
+
+- `_underscore/Model/Client/BundleItem.php` declares `isActive` / `isRequired` / `isVisible` as
+  plain `FIELD_BOOLEAN` columns with **no validation logic**.
+- `_underscore/Model/Client/SalesOrderItem.php` has **no pre/post API payload interceptor** and no
+  `_Exception_Validation` throw site — it is plain metadata-driven CRUD.
+
+## Recommended direction (decided 2026-08-27, not implemented, no ticket yet)
+
+**Enforce selectability at the API boundary, not by hardening the client filter.** A `prePost`
+API payload interceptor on the `sales-orders` record should re-derive each posted
+`salesOrderItems[].bundleItem` against its bundle and reject anything not currently selectable,
+throwing `_Exception_Validation` (→ clean 400, no `Logs.Issue`, no Sentry noise — per the
+exception-routing rule in `2.0/standards/backend-php.md`). Rationale: the client-side filter cannot
+be made trustworthy while flag semantics vary by row type, and a client-only fix leaves the direct
+API path wide open.
+
+Also decided: **delete** the dead `where` clause in `BundleApi.tsx` rather than "fix" it — the V2
+engine cannot prune nested children via `where` at all, and the clause could not express the
+fee / child-bundle exceptions even if it worked.
+
+## Gotchas / known issues
+
+- **⚠ Never read a flag on a `BundleItems` row without first knowing its row type.** Fee rows are
+  invisible-but-mandatory; child-bundle rows are inactive-by-convention.
+- **⚠ Do not add a `where` to a uuid'd GET expecting nested filtering.** It is doubly inert (READ
+  branch ignores it; `where` filters root rows only).
+- **⚠ A `where` field with an unknown table prefix reaches SQL verbatim.** `V2.php:6959-6962` only
+  prepends the default table when the field has no `.`, and no auto-join is generated for an
+  arbitrary prefix. A typo'd prefix becomes an unknown-column SQL error, not a validation message —
+  and on the READ path it is never even evaluated, which is exactly how the `BundlesItems` typo
+  survived unnoticed.
+- **Latent, reported unused:** `src/pages/BundleView/hooks/useBundleEditFromLocalStorage.ts`
+  (L21-35) restores `bundleProgressContents` and `optionalAddons` verbatim from localStorage with
+  **zero flag re-validation**. It is mechanically reachable (`isEdited: true` set by
+  `addOptionalChildBundleToParent` / `removeOptionalChildBundleToParent` in
+  `useBundleBuilderZu.ts`), but the flow is **reported unused by anyone as of 2026-08-27** and is
+  ruled out as the cause of `SA136441`.
+
+## Open question (unresolved)
+
+Which carve-out actually admitted part number `S24D402GAN` into order `SA136441` is **still
+unknown** — the API response inspected was truncated before that line, so its `BundleItems` row was
+never seen. Resolving it needs, for `S24D402GAN` in bundle 189: `isActive` / `isVisible` /
+`isRequired`, `childBundleId`, and `item.assetType.name`. If it is neither a FEE-assetType row nor a
+childBundle row, no fresh-load path explains it, and the next place to look is the cart sync or a
+direct API write (`Logs.Api` request payload for that order).
+
+## Change history
+
+- 2026-08-27 — Created from an investigation-only session (no code changed) into how part number
+  `S24D402GAN` reached Compass USA order `SA136441`. Recorded that the bundle fetch's
+  `BundlesItems.isActive` `where` clause in `BundleApi.tsx` has **never executed** (uuid'd GET
+  ignores `where`; `where` cannot prune nested children; and the table name is a typo for
+  `BundleItems`), so 100% of visibility/selectability enforcement is client-side; the two deliberate
+  raw-array carve-outs in `formatOriginalBundleData.ts` (fees at L81 with no `isVisible` check and
+  force-added as `updatedFees`; child bundles at L29 ignoring all three flags); the real
+  `Client.BundleItems` flag conventions (fees invisible-but-mandatory, child bundles
+  intentionally inactive) and the consequence that flag meaning varies by row type; and that
+  neither `_Model_Client_BundleItem` nor `_Model_Client_SalesOrderItem` validates selectability, so
+  a direct API caller can post any bundleItem uuid. Decided to enforce via a `sales-orders`
+  `prePost` interceptor throwing `_Exception_Validation` and to delete the dead `where` clause.
+  (apeterson)
+</content>
+</invoke>

package/knowledge/INDEX.md

@@ -29,7 +29,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **talos** (TOGa IQ) — 7 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 13 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
-- **toga2-commerce** (TOGa Commerce) — 19 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga2-commerce** (TOGa Commerce) — 20 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 13 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 13 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 - **bdr** (BDR) — 0 doc(s) → [2.0/apps/bdr/INDEX.md](2.0/apps/bdr/INDEX.md)

package/package.json

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