toga-ai 1.0.886 → 1.0.887

package/knowledge/2.0/apps/api2/features/nested-relationship-writes.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-09-23
+updated: 2026-09-24
 owners: ["bala", "mhammontree", "tcox", "apeterson", "rgirish", "jcardinal"]
 files:
   - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateTransferOrder.ts
@@ -17,6 +17,7 @@ files:
   - _underscore/Model/Elite/TransferOrderStage.php
 related:
   - ../architecture.md
+  - ../../toga25-supply/features/bundle-item-pricing.md
   - ../../../1.0/apps/library/features/netsuite-item-assettype-sync.md
   - ../../toga2-supply/features/currency-amount-lines-editor.md
   - cxml-shipnotice-gateway.md
@@ -157,6 +158,22 @@ WHERE recordId = 351 AND field = 'c_netsuiteInternalTransferOrderStatus';
 
 `recordId 351` is `transfer-order-stages`; the equivalent row exists per tenant with a **different `id`** but often the **same `uuid`** (both Elite and NYCHH carry `b273f4d1-dac0-4093-ad1d-7c3a526ab894`), the tell that the row came from one shared seed and only one tenant's copy has the wrong flag.
 
+### ⚠ An inherent child nested in a **PUT** is ALWAYS written as a CREATE
+
+The engine recurses into a nested one-to-many child (`Core.InherentRecordChildren`) with
+`httpMethod: 'POST'` **hardcoded** (`V2.php:5415`). There is no uuid check and no PUT branch, so a
+child nested in an update is never updated:
+
+| Nested child payload on a `PUT` | Result |
+|---|---|
+| no `uuid` | a **duplicate row** is inserted; the parent looks unchanged |
+| `uuid` of the existing row | fails — `EV-10` / MySQL `Error #: 1062 Duplicate entry … for key '<Table>_UNIQUE'` |
+
+**Correct pattern: nest children only on a CREATE.** To change an existing child, send its own
+`PUT /v2/<child-route>/{uuid}` after the parent write (two calls). This is general engine
+behaviour — it bites any write to a nested child, not one feature. Worked example:
+[bundle item pricing](../../toga25-supply/features/bundle-item-pricing.md).
+
 ### Nested inherent-child create — parent FK is auto-set, any depth
 
 - V2 auto-sets the child's FK to the parent: first field whose `FIELDOPT_FOREIGNKEY_MODEL` equals the parent class (exact normalized `_Model_Client_` string), then break (`V2.php` ~5211-5221). Payload supplies the OTHER FK only (e.g. bridge row `{ purchaseOrder: { uuid } }` under a transfer order).
@@ -166,6 +183,7 @@ WHERE recordId = 351 AND field = 'c_netsuiteInternalTransferOrderStatus';
 
 ## Gotchas
 
+- **⚠ A nested inherent child on a PUT is created, never updated** (`V2.php:5415` hardcodes `POST`) — you get a duplicate row, or a 1062 duplicate-key error if you send the child's `uuid`. Update children through their own route.
 - **Nested write with only a non-identifier field silently creates duplicates.** A duplicate-generating footgun: each write inserts a new empty child and the parent links to a fresh shell (or is left with a NULL FK). It compounds on any cron/integration that writes the same entity repeatedly. Root-caused in production on the Prudential device-sync cron, which sent `contact: {c_employeeXid}` and generated ~893k empty Contact rows (~5,600/day). See [Prudential device import + contact linking](../../../clients/prudential/features/device-information-import-and-contact-linking.md).
 - **A matched nested object is UPDATED, not just linked** — partner data can mutate shared catalog rows. Matching is not read-only.
 - **A `NULL` `overrideIsIdentifier` unsets the field as an identifier** — a row added only to set a child policy silently strips it, causing EV-12. Correct only where `Core.RecordFields.isIdentifier = 1`; ship it as a `dbchanges2/Client_<Tenant>/` migration (a manual non-prod patch evaporates on reseed).
@@ -177,6 +195,11 @@ WHERE recordId = 351 AND field = 'c_netsuiteInternalTransferOrderStatus';
 - **Declaring a `c_` field on the model does not make it searchable** — the `CustomRecordFields.isIdentifier` flag is the gate; set the flag, not the child policy.
 - **Singular-FK back-reference defects:** UPDATE path drops the parent's forward FK (echoes `null`); CREATE path re-parents a value-matched child to the newest writer (stolen child row). One defect, two symptoms.
 
+## Change history
+- 2026-09-24 — Documented that the engine recurses into a nested inherent child with `POST`
+  hardcoded (`V2.php:5415`), so a child nested in a PUT is duplicated or fails 1062; update
+  children through their own route (TRUE-82138). (apeterson)
+
 ## Related
 
 - [api2 architecture](../architecture.md) — the V2 CRUD engine (`processRoutePairs`).

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

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-09-23
+updated: 2026-09-24
 owners: [tcox, bala, apeterson, jcardinal, rgirish]
 files:
   - api2/Component/Api/V2/V2.php
@@ -64,6 +64,24 @@ controller.
   the join is genuinely 1:1, or the duplicates agree. Worked example:
   [category tile sort order](../../toga2-commerce/features/category-tile-sort-order.md).
 
+### ⚠ `depth` and `calcDepth` are IGNORED inside the base64 `_` options blob
+
+`fields`, `where`, `sort`, `join` work inside the `_` blob. **`depth` and `calcDepth` do not** —
+they are only read as plain query params. Silent: no error, the request just runs at the defaults
+(`depth 3`, `calcDepth 1`), so nested calculated fields come back absent and the engine looks
+incapable of returning them. Mixing is fine — put the blob in `_` and add `&calcDepth=2`.
+(toga-blox `assembleOptions` already appends any unrecognised option key to the query string,
+which is why mixed requests work from the FE.) Verified 2026-09-24 (TRUE-82138).
+
+### ⚠ A field THREE levels under an inherent child is silently DROPPED, at any depth
+
+Distinct from the max-depth omission above — raising `depth` does not help. A field two hops below
+an inherent child (`bundleItems.bundleItemPrices.priceType` on `GET /v2/bundles/{uuid}`) is absent
+from the payload with no error and no message; the same field is returned by the shallower
+`GET /v2/bundle-items/{uuid}`. **Consequence:** a caller cannot tell one child row from another
+(e.g. a unit-price row from a lease-price row) on the parent payload, and must not guess — fetch
+the child route instead.
+
 ### How `sort` becomes `ORDER BY` — and why "descending sort is broken" is usually just NULLs
 
 `ORDER BY` is a **plain string concatenation** of the resolved column and `ASC`/`DESC` — no cast, no
@@ -565,6 +583,7 @@ If you need the behaviour, loop uuids client-side. Point 3 is the durable, non-o
 - **⚠ A 500 / `EO-1` on a `where` over a calculated field ⇒ you table-PREFIXED the field name.**
   Drop the prefix: `_qtyAvailable`, not `PurchaseOrderItems._qtyAvailable`. The prefixed form is
   routed to a `HAVING` against an alias that does not exist.
+- **⚠ `depth`/`calcDepth` inside the `_` blob do nothing** — send them as plain query params.
 - **⚠ Do not raise `calcDepth` for a calculated field you named in `fields=`** — it is classified
   before the gate and already resolves at the default `1`.
 - **Do not trust a 200 with missing fields.** Without an explicit `fields=` list, ACL removal is
@@ -585,6 +604,9 @@ If you need the behaviour, loop uuids client-side. Point 3 is the durable, non-o
   [V2 request logging](request-logging.md).
 
 ## Change history
+- 2026-09-24 — Recorded that `depth`/`calcDepth` are ignored inside the base64 `_` options blob
+  (plain query params only), and that a field three levels under an inherent child is silently
+  dropped at any depth (TRUE-82138). (apeterson)
 - 2026-09-23 — Documented how `sort` becomes `ORDER BY` (plain concatenation, no cast or NULL
   handling), that the same expression doubles as the keyset-pagination cursor so any change must be
   mirrored in the seek `WHERE`/`getSeekFieldType()`, and that "descending sort is broken" reports are

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

@@ -4,6 +4,7 @@
 |-----|---------|
 | [TOGa 2.5 Supply — Architecture](architecture.md) | Architecture of toga25-supply — the React/TS Vite SPA frontend for 2.0 Supply, multi-client + meta-driven, built on `@agilant/toga-blox`; open before any struct |
 | [Action-Button Rule Engine (Flag / Rule grammar)](features/action-button-rule-engine.md) | Declarative config-driven Flag/Rule grammar that resolves `isEnabled`/`isVisible`/`isComplete` on SalesOrder action-button options and approval stage inputs (ev |
+| [Bundle item pricing (unit / lease rows, edit save path, duplicate rows)](features/bundle-item-pricing.md) | How a bundle item's unit/lease price is read, displayed and SAVED in supply — the two-call save (never nest the price in a PUT), `_unitPrice`/`_leasePrice` + `c |
 | [Client API-Fetch Fields (useClientApiFields / apiFields.json)](features/client-api-fetch-fields.md) | Resolves a client's API-fetch projection (`fields`/`ojoin`/`join`/`where`) from one colocated per-page `apiFields.json` keyed by client slug (useClientApiFields |
 | [Client-Configurable Fields (useClientFields / fieldsConfig)](features/client-configurable-fields.md) | Config that varies by client (or client × role) — field overrides, filter buttons, group-by, column pickers, layout toggles — resolved through `src/fieldsConfig |
 | [Column State (URL-driven show/hide, order & pinning)](features/column-visibility.md) | URL-driven "Columns" button + modal (`cols` param) for show/hide + order + pinning of table columns, client-configurable then Surface-driven; open for column-vi |

package/knowledge/2.0/apps/toga25-supply/features/bundle-item-pricing.md

@@ -0,0 +1,89 @@
+---
+title: Bundle item pricing (unit / lease rows, edit save path, duplicate rows)
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-09-24
+owners: ["apeterson"]
+files:
+  - toga25-supply/src/layout/BundleItemRecordModalLayout/hooks/useBundleItemEditForm.tsx
+  - toga25-supply/src/layout/BundleRecordModalLayout/types.ts
+  - toga25-supply/src/layout/BundleRecordModalLayout/viewModel/FIELDS/DEFAULT/bundleRecordViewFields.json
+  - toga25-supply/src/layout/BundleRecordModalLayout/components/BundleItemsTable.tsx
+  - dbchanges2/Client_Compass/2026-09-24a - DeduplicateBundleItemPrices.sql
+related:
+  - ../../api2/features/nested-relationship-writes.md
+  - ../../api2/features/v2-rest-query-contract.md
+  - ../../_underscore/features/calculated-sql-fields.md
+  - ./record-modals-and-nested-tables.md
+  - ../../../clients/compass-usa/workflows/changing-a-kit-line-item.md
+---
+
+How a bundle item's unit/lease price is read, displayed and SAVED in supply — the two-call save (never nest the price in a PUT), `_unitPrice`/`_leasePrice` + `calcDepth: 2`, and the duplicate `BundleItemPrices` rows.
+
+## Summary
+
+A bundle item has **many** `BundleItemPrices` rows, one per `priceTypeId` (unit, lease-48, …).
+Supply shows Default Price Type / Unit Price / Lease Price in the bundle items table and edits a
+price in the bundle-item modal. Two engine behaviours shape all of it: nested children are never
+updated on a PUT, and the calculated price fields need `calcDepth: 2` when read through a bundle.
+
+## How it works
+
+### Reading — `_unitPrice` / `_leasePrice`
+
+Both are `FIELD_SQL` calculated fields on `_Model_Client_BundleItem`: they resolve the row
+matching `defaultPriceTypeId` with `ORDER BY id DESC LIMIT 1` (**newest** row wins).
+
+- The table columns are sourced from these fields, not from the `bundleItemPrices` array.
+- For **nested** bundle items (inside `GET /v2/bundles/{uuid}`) they need **`calcDepth: 2`**, sent
+  as a **plain query param** — inside the base64 `_` blob it is ignored. At the default `calcDepth: 1`
+  both fields are silently absent. See
+  [V2 REST query contract](../../api2/features/v2-rest-query-contract.md).
+- `priceType` on a nested price row is **never returned** by `GET /v2/bundles/{uuid}` (three levels
+  under an inherent child — dropped silently). Re-fetch `GET /v2/bundle-items/{uuid}` when you need
+  typed rows.
+
+### Saving — two calls, never a nested price in a PUT
+
+The V2 engine writes a nested inherent child with `POST` hardcoded, so a price nested in a **PUT**
+inserts a duplicate row (or fails 1062 if you send its uuid) —
+[nested-relationship writes](../../api2/features/nested-relationship-writes.md).
+
+1. `PUT /v2/bundle-items/{uuid}` — **without** the nested price.
+2. `PUT /v2/bundle-item-prices/{uuid}` — the price row.
+
+**Create still nests** (correct there — it is a POST).
+
+`resolvePriceRowUuid` picks the row to update **strictly by `priceType`**. If the payload rows carry
+no `priceType`, it re-fetches typed rows from `/bundle-items/{uuid}`; if the type still cannot be
+established it **creates a new row** rather than overwriting an unknown one. Never fall back to
+"the newest row" — during a unit-price edit that can overwrite the LEASE price.
+
+## Gotchas
+
+- **⚠ An edited price that looks unchanged on screen is the duplicate-row bug.** `_unitPrice` reads
+  the newest row (`ORDER BY id DESC`) while the FE rendered `bundleItemPrices[0]` (the oldest) — the
+  insert was invisible in the UI for a long time.
+- **⚠ Duplicate `BundleItemPrices` rows already exist in production data**, predating this front end
+  (one bundle item has 15 rows, ids 13→4355). The table has no `dtCreated`/`dtUpdated`, so age cannot
+  be proven. Local-copy counts: `Client_Compass` 5117 rows / 2605 duplicates / 971 groups (36 groups
+  with differing prices); `Client_CompassCanada` 333 / 75 / 63; all other tenants zero. **Prod counts
+  not yet taken.**
+- **Dedupe migrations exist but have only been run locally** —
+  `dbchanges2/Client_Compass/2026-09-24a - DeduplicateBundleItemPrices.sql` and the
+  `Client_CompassCanada` twin keep `MAX(id)` per `(bundleItemId, priceTypeId)` — the row the
+  calculated fields already read, so nothing changes on screen. Safe to run: no foreign key anywhere
+  references `BundleItemPrices`, and `SalesOrderItems` snapshots its own price column, so no order or
+  quote is affected. `currencyId`/`planId` are NULL on every row.
+- **⚠ FIELDS JSON edits appear to do nothing** — the persisted React Query cache freezes them; see
+  [persisted query cache](./persisted-query-cache.md).
+
+## Change history
+- 2026-09-24 — Documented the two-call save (price edits were inserting duplicates via a nested PUT),
+  the strict-`priceType` row match with create-not-guess fallback, the `_unitPrice`/`_leasePrice`
+  columns needing `calcDepth: 2` as a plain query param, and the Compass/Compass Canada
+  `BundleItemPrices` dedupe migrations (TRUE-82138). (apeterson)

package/knowledge/2.0/apps/toga25-supply/features/persisted-query-cache.md

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
+updated: 2026-09-24
 owners: ["apeterson"]
 files:
   - toga25-supply/src/App.tsx
@@ -145,7 +145,11 @@ Type-check **both** `-p tsconfig.app.json` and `-p tsconfig.node.json` — `vite
 
 - **⚠ A non-zero `staleTime` on a persisted query serves yesterday's data and never fetches.** Data hooks in this app use `staleTime: 0`. Hooks that currently break this rule **and are persisted**: `useClientFields`, `useCurrentUser`, `useStatusTypeValues`, `useStatusColors`, `useSalesOrderUuidForServiceRequest` (all `Infinity`), and the three VendorItem form hooks (`5 * 60_000`). Each can serve a previous session's answer.
 - `useTalosSession` and `useTalosThreads` also set a non-zero `staleTime`, but their keys start with `talos`, so they are **not** persisted — in-memory only, safe.
+- **⚠ An edit to a client `FIELDS` JSON looks like it does nothing — and it is NOT Vite HMR.** `useClientFields` is `staleTime: Infinity` **and** persisted, so the old config is frozen in `supply-chain-query-cache`. Clear that key to see the edit. Proper fix: exclude `clientFields` in `shouldDehydrateQuery` (`src/App.tsx:42`).
 - **⚠ Never verify a config, surface, or ACL change on a warm browser.** Log out, or delete the `supply-chain-query-cache` key in devtools. Most "it didn't deploy" reports are a rehydrated cache.
 - **⚠ `gcTime: 0` does not stop persistence.** It only evicts a query once it becomes *inactive*; an active query is still dehydrated. To keep something off disk, exclude its namespace in `shouldDehydrateQuery`.
 - **⚠ Any new `queryClient.clear()` must `await awaitRestoration()` first**, or the restore race undoes it.
 - The `maxAge` is one timestamp for the entire blob — you cannot expire a single query through it.
+
+## Change history
+- 2026-09-24 — Noted the frozen-`FIELDS`-JSON symptom (persisted `useClientFields` at `staleTime: Infinity`, mistaken for broken Vite HMR) and the `shouldDehydrateQuery` fix. (apeterson)

package/knowledge/INDEX.md

@@ -33,7 +33,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **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) — 26 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
-- **toga25-supply** (TOGa 2.5 Supply) — 21 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
+- **toga25-supply** (TOGa 2.5 Supply) — 22 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 15 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.886",
+  "version": "1.0.887",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",