toga-ai 1.0.289 → 1.0.291

package/knowledge/2.0/apps/_underscore/features/surface-resolver.md

@@ -98,6 +98,26 @@ which surfaced latent resolution gaps in `_buildBundle`/`_resolveElement`:
 - `bundle.surface.titleMessageKey` is set from `titleMessageId`.
 - The 2nd `_loadMessages` return is merged into `$messageKeyById`; dangling message ids are logged.
 
+## Vocabulary / label per-client relabeling (slugs are internal, labels are messages)
+
+Clients **never rename a Vocabulary**. `Vocabularies.slug` (`sales-order-status`) and
+`VocabularyTerms.value` (`pendingApproval`) are **stable internal identifiers, never shown to
+users**. The displayed label always resolves from **`Core.Messages`** (every visible string is a
+message key; per-term labels come from each `VocabularyTerm.labelMessageId`). A client customizes
+the *displayed* name two ways, **without touching Core**:
+
+1. **`SurfaceOverrides` row with `attribute = LABEL_MESSAGE`** — scoped by persona/role/language —
+   re-points an element's label to a different message.
+2. **`MessageTranslations` row** (per `languageId`; a null translation falls back to
+   `Messages.defaultValue`).
+
+Because status-comparison / gating rules compare the **`value`**, not the label, relabeling never
+breaks logic.
+
+> ⚠ **Unverified — flag for future confirmation:** whether a `SurfaceOverrides.attribute =
+> LABEL_MESSAGE` value stores a **message id** or a **raw message key** is not yet confirmed. Verify
+> against `Model/Core/Surface.php` `_loadOverrides`/`_buildBundle` before relying on either form.
+
 ## Caching & invalidation
 
 - Disk cache keyed `surface:meta:{app}:{slug}:{client}:{sortedPersonaIds}:{sortedRoleIds}:{lang}`.
@@ -214,6 +234,12 @@ Core record grants + their logic-group expressions all evaluate `all`/`"1"`. The
   match Compass, a follow-up migration aligning both `meta` and `meta-group` to roles 1,3,4 is needed.
 
 ## Change history
+- 2026-07-01 — Clarified vocabulary/label per-client relabeling (new section): Vocabulary `slug`
+  and VocabularyTerm `value` are stable internal ids never shown to users; the displayed label
+  always resolves from `Core.Messages`; clients relabel via a `SurfaceOverrides` `LABEL_MESSAGE`
+  override (persona/role/language-scoped) or a `MessageTranslations` row (null → `defaultValue`),
+  and status-comparison rules compare `value` not the label so relabeling never breaks logic.
+  Flagged unverified: whether `LABEL_MESSAGE` stores a message id vs a raw key. (apeterson)
 - 2026-07-01 — Documented the full route-level authorization mechanism (new section): the surfaces
   script gate is `Client_<tenant>.AclRecordScripts` keyed on JWT `id.client.roles` (client roles,
   not `core.roles`, not `Core.AclRecordPermissions`); element-drop is a separate

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

@@ -3,5 +3,5 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Database Changes (dbchanges2) Repository Architecture](architecture.md) | `dbchanges2` is the **schema-migration / SQL change-set repository** for the entire 2.0 platform. | Core/, Client/, Client_<Tenant>/, Logs/, Logs_Client/, _modules/ |
-| [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql |
+| [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql |
 | [2.0 New-Client Onboarding (manual process)](workflows/client-onboarding.md) | How to manually stand up a new 2.0 client (tenant). | Client/, Client_<Tenant>/, Core/, Logs_Client/ |

package/knowledge/2.0/apps/dbchanges2/features/surface-layer-schema.md

@@ -6,9 +6,13 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-06-30
-owners: [jcardinal]
+updated: 2026-07-01
+owners: [jcardinal, apeterson]
 files:
+  - dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql
+  - dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql
+  - _underscore/Model/Client/ThemeToken.php
+  - toga25-supply/src/themeConfig.json
   - dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql
   - dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql
   - dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql
@@ -57,13 +61,41 @@ per-tenant deltas live in **Client** (mirrors `TableViews`/ACL/`ItemTranslations
 | `Messages` | Core | i18n key catalog + ICU default value |
 | `SurfaceOverrides` | Client | THE single sparse cascade table (+`c_longValue mediumtext`) replacing ~40 EAV tables |
 | `MessageTranslations` | Client | per-language overlay (sidecar pattern) + `c_longValue` |
-| `ThemeTokens` | Client | per-tenant semantic token → value (the only place a hex/icon name lives) |
+| `ThemeTokens` | Client | per-tenant semantic token → value (the only place a hex/icon name lives) — see ThemeTokens section below |
 
 `SurfaceOverrides` carries the entire cascade in one sparse table: scope columns
 `personaId`/`roleId`/`languageId` (NULL = not scoped on that axis), an `attribute` ENUM, and
 `value varchar(255)` + `c_longValue mediumtext`. Precedence **base < client < persona < role**
 with language as an orthogonal overlay; the resolver applies it most-specific-last in one pass.
 
+## ThemeTokens — per-tenant, physically isolated in each client DB
+
+`ThemeTokens` lives **inside each tenant's own database** (`Client_Compass.ThemeTokens`,
+`Client_Quad.ThemeTokens`, `Client_CompassCanada.ThemeTokens`) — **not** in Core. Per-tenant
+physical DB isolation is the multi-tenancy mechanism; there is no confirmed Core-held default
+ThemeTokens table. It is a **flat `slug → value` map** (no nesting):
+
+| Column | Type | Notes |
+|---|---|---|
+| `slug` | varchar(64), UNIQUE | e.g. `color.status.approved` |
+| `category` | ENUM(`COLOR`,`BACKGROUND`,`SPACING`,`RADIUS`,`TYPOGRAPHY`,`ICON`) | |
+| `name` | varchar | human label |
+| `value` | varchar(64) | resolved hex / css unit / icon name |
+
+`_Model_Client_ThemeToken.php` is the ORM model; `_Model_Core_Surface::resolve()` reads the
+tenant's tokens during resolve to map element token-slugs → values (see
+[surface-resolver](../../_underscore/features/surface-resolver.md)).
+
+**Seed gap (known, not a capability gap):** the current Compass seed
+(`Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql`) covers **only semantic status
+tokens** (~15 statuses × fg `color.status.*` + bg `bg.status.*` ≈ 30 rows). The ~1004 design-
+foundation CSS vars (`--btn-*`, `--baseInput-*`, `--sideNav-*`, …) are **not** in the DB — they
+still live only in the frontend file `toga25-supply/src/themeConfig.json` (single DEFAULT theme).
+The `category` enum already includes `SPACING`/`RADIUS`/`TYPOGRAPHY`/`ICON`, so the table is
+**designed** to hold the full foundation eventually; it just isn't seeded with it yet. Migrating
+the foundation into `ThemeTokens` rows is the target end-state (see the theming-architecture
+decision, held for senior review).
+
 ## Migration files (typed columns, not EAV)
 
 CREATE order is FK-safe (`Messages → Actions → Vocabularies → VocabularyTerms → Surfaces →
@@ -158,6 +190,12 @@ SurfaceElements`). Core migrations run first; Client after. The session built/se
   because `TOOLTIP_MESSAGE` is numeric-only (cosmetic, deferred).
 
 ## Change history
+- 2026-07-01 — Documented `ThemeTokens` in detail (new section): it lives **inside each tenant's
+  own DB** (physical isolation, no confirmed Core default table), is a flat `slug→value` map with
+  the `category` ENUM(`COLOR`/`BACKGROUND`/`SPACING`/`RADIUS`/`TYPOGRAPHY`/`ICON`), and read by
+  `resolve()`. Recorded the known seed gap: only status tokens are seeded (~30 rows); the ~1004
+  design-foundation vars still live only in `toga25-supply/src/themeConfig.json` — the table is
+  designed to hold the foundation but isn't seeded with it yet. (apeterson)
 - 2026-06-30 — Added the SalesOrders SECTION-surface migration seeds: Core `meta-group` RecordScript +
   `order-recurring` + 5 display-toggle SECTION surfaces (each with a `sectionVisibility` marker
   element, since the cascade overrides elements not a surface's own isVisible), the `meta-group`

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 |
+| [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 Page — config-driven form architecture (current state + planned refactor)](features/cart-page-config-architecture.md) | The Cart page (`src/pages/Cart/`) is the most config-heavy page in `toga2-commerce`. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/pages/Cart/view/cartForm/CartFormSection.tsx, src/pages/Cart/view/cartForm/CartFormRenderer.tsx, src/pages/Cart/view/EditCart.tsx, src/pages/Cart/view/EditOrder.tsx, src/pages/Cart/viewModel/useEditOrderOrEditCartViewModel.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts, src/hooks/useAssignClientFields.ts |
 | [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Almost no user-facing text, field layout, or page config is hard-coded in `toga2-commerce`. | src/fieldsConfig/index.ts, src/fieldsConfig/getClientLoginFields.ts, src/fieldsConfig/clientFields/COMPASS.json, src/fieldsConfig/clientFields/COMPASSCANADA.json, src/fieldsConfig/clientFields/QUAD.json, src/hooks/useAssignClientFields.ts, src/hooks/useDynamicConditionalFieldOptions.ts, src/stores/useFieldsStore.ts, src/components/BaseDetailField/BaseDetailField.tsx |

package/knowledge/2.0/apps/toga2-commerce/features/cart-bundle-submission-and-identity.md

@@ -0,0 +1,97 @@
+---
+title: Cart Bundle Submission & the bundleUuid Identity Contract
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-07-08
+owners: ["apeterson"]
+files:
+  - 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
+related:
+  - 2.0/apps/toga2-commerce/architecture.md
+  - clients/compass-usa/workflows/cross-kit-bundle-corruption.md
+---
+
+## Summary
+
+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 consumer of a cart bundle
+must obey: the cart bundle object (`BundleForZuCart`) exposes **`bundleUuid`** as its identity —
+there is **no `uuid` field** on it. Reading `bundle.uuid` returns `undefined` and silently
+corrupts kit/fee attribution.
+
+## How it works
+
+The cart (`useCartStoreZu`) holds bundles alongside loose items. On submit/edit,
+`syncSalesOrderItemsFromLocalStorageCartToApi.ts` (`syncSalesOrderLocalStorage`) builds the
+`SalesOrderItems` payload:
+
+- Loose items are pushed directly.
+- For each cart bundle, `processBundleContents(bundle.bundleProgressContents, salesOrderItems,
+  bundle.bundleUuid)` emits the kit's product lines, stamping each with the bundle's identity.
+- A second loop emits each bundle **fee** line, matching an existing SO item on **both**
+  `item.uuid` **and** `bundleItem.bundle.uuid === bundle.bundleUuid` so a fee is not matched
+  across bundles, then setting `bundleItem.bundle.uuid = bundle.bundleUuid`.
+
+Downstream, `updateParentSalesOrderItemId` links each child line to its kit's **primary** by
+comparing bundle identity, and `useCartSalesQuoteZu.updateSalesOrderItem`'s `findIndex` uses
+`item.uuid` **plus** the bundle identity to place a line in the right kit.
+
+On the read side, `formatSalesOrderBundlesFromApi.ts` (via `pairSalesOrderBundlesFromApi`)
+rebuilds the cart bundles from the API by grouping API lines on their `parentSalesOrderItem`
+identity.
+
+## The bundleUuid identity contract
+
+- `BundleForZuCart` exposes **`bundleUuid`** (the bundle/kit identity) and
+  **`bundleZuCartUuid`** (the per-cart-instance id). It has **no `uuid`**.
+- Any code consuming a cart bundle must read **`bundleUuid`** (or `bundleZuCartUuid` when it
+  needs the per-cart instance) — never `bundle.uuid`.
+- The producer field was renamed `uuid` → `bundleUuid` in commit **e5115167** *"Fix bundle
+  formatting during edit"* (2026-03-18), in `formatSalesOrderBundlesFromApi.ts` and
+  `useCartStoreZu.ts`. Several consumers were **not** updated at the time.
+
+## Gotchas
+
+- **Cart bundles flow through variables typed `any`** (`cartBundles.forEach((bundle: any) => …)`),
+  so TypeScript does **not** flag a wrong field read. A stale `bundle.uuid` compiles cleanly and
+  yields `undefined` at runtime — grep every new consumer by hand.
+- **`bundle.uuid` (undefined) mis-attributes kit lines/fees.** When the submit path read
+  `bundle.uuid`, every emitted line got `bundleItem.bundle.uuid = undefined`, so (a)
+  `updateParentSalesOrderItemId` compared `undefined == undefined` → true for every line against
+  every primary, collapsing lines onto the **last** kit's primary; and (b)
+  `updateSalesOrderItem`'s `findIndex` degraded to matching on `item.uuid` alone — so lines that
+  **share** an `item.uuid` across kits (fees/warranties, the same catalog item reused in every
+  kit) collided and merged into the wrong kit. Products with unique `item.uuid`s mostly survived;
+  shared fee items reliably broke. This is why it only reproduced on **multi-kit orders that
+  share fee items**.
+- **The code fix is preventive only.** Correcting the submit reads stops *new* corruption on
+  save; it does **not** heal already-persisted bad rows. Existing corrupted orders still render
+  fees under the wrong kit on edit because `pairSalesOrderBundlesFromApi` rebuilds the cart by
+  grouping on the (corrupted) `parentSalesOrderItem` identity from the API. See the Compass
+  detect-and-repair workflow (in `related`).
+- **Still-stale consumers (not yet fixed, as of 2026-07-08):**
+  - `src/pages/OrderDetails/helpers/formatSalesOrderDataFromLocalStorage.ts:130` — `uuid:
+    bundle.uuid` (cosmetic: an `undefined` display field).
+  - `src/pages/OrderDetails/view/components/OrderItems.tsx:45` — React `key={bundle.uuid}`
+    (cosmetic: duplicate/`undefined` keys).
+  - `src/api/helpers/formatBundlesForSalesQuoteZuCartInEditMode.ts:82` still reads the old field
+    but is **dead code** (no imports).
+
+## Change history
+- 2026-07-08 — Fixed edit-order bundle submission attributing kit items/fees to the wrong kit:
+  `syncSalesOrderItemsFromLocalStorageCartToApi.ts` read `bundle.uuid` (undefined) instead of
+  `bundle.bundleUuid` at 3 sites; corrected all three. Root cause traced to the 2026-03-18
+  `uuid → bundleUuid` producer rename (commit e5115167) that left stale consumers. Fix is
+  preventive (does not heal persisted rows) and lives on branch TRUE-80097, not yet merged.
+  Documented the `bundleUuid` identity contract and the two remaining cosmetic stale consumers.
+  (apeterson)
+</content>
+</invoke>

package/knowledge/2.0/standards/backend-testing.md

@@ -5,9 +5,12 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-07-02
+updated: 2026-07-08
 owners: [mhammontree]
-files: []
+files:
+  - _underscore/Query.php
+  - _underscore/Database.php
+  - _underscore/Environment.php
 related:
   - ../apps/_underscore/architecture.md
   - ../apps/_underscore/features/per-client-database-connections.md
@@ -27,12 +30,22 @@ From a 2.0 app root (e.g. `worker2`): `chdir` into the app, require Composer aut
 `_underscore.php`, and set `ENVIRONMENT` before bootstrap:
 
 ```php
+putenv('ENVIRONMENT=dev-markhammontree-laptop'); // REQUIRED, before requiring _underscore.php
+                                                 // e.g. dev-<yourname>-laptop — matches your Config/<ENVIRONMENT>.ini
 chdir('/path/to/worker2');
 require 'vendor/autoload.php';
 require '_underscore.php';   // boots Loader/Config/etc.
-// ENVIRONMENT must be set (env var / server) so _Config picks the right INI
 ```
 
+- **`ENVIRONMENT` is mandatory.** The bootstrap uses it to select `worker2/Config/<ENVIRONMENT>.ini`.
+  If it is unset, `_underscore.php` throws *"The environment variable 'ENVIRONMENT' is required and
+  has not been set"* (`_underscore/Environment.php:12`). Set it via `putenv(...)` in the script
+  before the `require`, or export it in the shell.
+- **On Windows the shell is PowerShell** — set env vars as `$env:VAR='x'; php script.php`, **not**
+  the bash `VAR=x php script.php` prefix. The bash-style prefix silently does nothing in
+  PowerShell, so the script falls back to its defaults (a confusing "it ran but used the wrong
+  config" failure).
+
 ## You MUST pin the client DB explicitly
 
 `_underscore::DB_CLIENT` is a **logical alias**, not a schema name — there is no database literally
@@ -51,8 +64,41 @@ Without this, any `Model/Client/*` query resolves the unmapped alias and fails.
 schema you have locally/on the target env (internal testing uses `Client_True` = TOGA Technology).
 Remember the per-client **logs** connection trap too (see the per-client-database-connections doc).
 
+## Commit before you read your own writes (lazy-transaction trap)
+
+Standalone scripts run under `_underscore`'s **lazy-transaction model with a separate read
+connection**, so a write is invisible to a later read — and to the code under test — until it is
+committed. Concretely:
+
+- `_Database::register(..., alias: _underscore::DB_CLIENT)` sets up a pending transaction for that
+  DB. The **first** write (via `_Query`) flips autocommit **OFF** and opens the transaction
+  (`_underscore/Query.php` ~303–304, keyed by the database value passed to `_Query`).
+- INSERTs therefore sit **uncommitted**. A subsequent `SELECT` on the read connection returns
+  nothing, so a read-back-by-marker returns `null` and dependent FK inserts fail (classic symptom:
+  `saleItemId = 0` FK violation).
+
+**Pattern:** after seeding base rows, call
+`_Database::transactionCommit(_underscore::DB_CLIENT)` (`_underscore/Database.php` ~165–212). This
+commits **and** restores `autocommit(true)`, so all later writes — and reads of them — behave
+normally. Order your script:
+
+1. seed base rows →
+2. **commit** →
+3. read ids back →
+4. insert dependent rows →
+5. assert →
+6. cleanup — and **commit the cleanup too**, so the `DELETE`s persist rather than being rolled
+   back when the script exits.
+
+This is the same lazy-transaction write-drop family noted in the `_underscore` architecture doc;
+it bites the standalone-script/verification case specifically. Demonstrated working in
+`test/@Mark/Rate/verify_wholehome_per_address_guard.php`.
+
 ## Rules
 
 - Do not add or assume a PHPUnit suite for 2.0 backend work; write a `test`-repo script instead.
+- Always set `ENVIRONMENT` before bootstrap (PowerShell: `$env:ENVIRONMENT='...'`, or `putenv`).
 - Always pin the concrete `Client_<Id>` schema to `DB_CLIENT` (and logs/archive if the code logs).
+- **Commit seeded rows before you read them back** — the read connection cannot see uncommitted
+  writes; commit cleanup too so it persists.
 - Keep scripts in your per-dev `test` folder; never point them at production databases.

package/knowledge/INDEX.md

@@ -28,7 +28,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) — 6 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
-- **toga2-commerce** (TOGa Commerce) — 7 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga2-commerce** (TOGa Commerce) — 9 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 8 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 7 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/knowledge/clients/compass-usa/INDEX.md

@@ -8,5 +8,6 @@
 | [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, library/app/client/compass.php |
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |
+| [Compass Cross-Kit Bundle Corruption — Detection & Repair](workflows/cross-kit-bundle-corruption.md) | 2.0 | A frontend regression in `toga2-commerce`'s edit-order bundle submission mis-attributed bundle (kit) line items and **fees/warranties** to the **wrong kit**, pe | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts |
 | [Compass ODP Order Pipeline to NetSuite (numbered worker crons)](workflows/odp-order-pipeline-to-netsuite.md) | 1.0 | The end-to-end **Compass Office Depot (ODP) order → NetSuite** pipeline as it actually runs through the 1.0 `worker` crons under `worker/crons/toga2/compass/`, | worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, worker/crons/toga2/compass/edi/1_download_edi_s3_create_po_toga.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, library/app/client/compass.php |
 | [Compass Order Lifecycle & Data-Integrity Invariants](workflows/order-lifecycle-and-data-integrity.md) | 2.0 | End-to-end map of how a Compass order flows through the `Client_Compass` (2.0) database and the **expected raw-data shape** at each link/ASN/IF level. |  |

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

@@ -14,13 +14,15 @@ project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-07-06
-owners: [jcardinal, bala, tcox]
+updated: 2026-07-08
+owners: [jcardinal, bala, tcox, apeterson]
 files: []
 related:
   - features/asn-to-item-fulfillment.md
   - features/cost-centers.md
+  - workflows/cross-kit-bundle-corruption.md
   - ../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
+  - ../../2.0/apps/toga2-commerce/features/cart-bundle-submission-and-identity.md
   - ../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
 ---
 
@@ -49,6 +51,11 @@ separate, related client (see its own profile).
   **Known data issue:** many Compass MacBooks are categorized `APPLE LAPTOP` /
   `MAC & ACCESSORIES`, not `COMPUTERS`, so those kits do **not** qualify for expedited — a
   catalog-data normalization matter, not a code gap.
+- **Cross-kit bundle corruption (edit-order):** a `toga2-commerce` submit bug attributed kit
+  line items and shared fees/warranties to the wrong kit; 55 Compass orders / 298 line items are
+  corrupted in `Client_Compass.SalesOrderItems` (Canada and Quad: zero). The code fix is
+  preventive; existing rows still need a DB data-fix. Detection query + remediation plan:
+  [Cross-Kit Bundle Corruption](workflows/cross-kit-bundle-corruption.md).
 
 ## Vendors & integrations
 - **Office Depot (ODP)** — vendor id 1. ASNs arrive via **cXML** (direct V2 API) and via the

package/knowledge/clients/compass-usa/workflows/cross-kit-bundle-corruption.md

@@ -0,0 +1,113 @@
+---
+title: Compass Cross-Kit Bundle Corruption — Detection & Repair
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: compass-usa
+type: workflow
+status: active
+updated: 2026-07-08
+owners: ["apeterson"]
+files:
+  - src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts
+related:
+  - 2.0/apps/toga2-commerce/features/cart-bundle-submission-and-identity.md
+  - clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md
+  - clients/compass-usa/profile.md
+---
+
+## Summary
+
+A frontend regression in `toga2-commerce`'s edit-order bundle submission mis-attributed bundle
+(kit) line items and **fees/warranties** to the **wrong kit**, persisting corrupted rows in
+`Client_Compass.SalesOrderItems`. Only **Compass** triggers it — it is the only tenant running
+the multi-kit-plus-shared-fee edit flow. This doc is the read-only **detection** reference and
+the **remediation** plan. The root cause is fixed (preventive), but **already-persisted rows are
+not healed** and still need a DB data-fix.
+
+Root cause and the field contract are in the toga2-commerce feature doc (see `related`); this
+doc covers the **data signature, impact, and repair** in `Client_Compass`.
+
+## The corruption signature
+
+A **flat kit child line** in `SalesOrderItems` where:
+- `bundleItemId` **IS NOT NULL** (it belongs to a kit), and
+- `bundleId` **IS NULL** (this excludes legitimate *nested* child-bundles, which set `bundleId`), and
+- `parentSalesOrderItemId` points to a primary whose kit differs from the line's own kit —
+  i.e. the child line's `BundleItems.bundleId` ≠ its parent primary's `BundleItems.bundleId`.
+
+The test joins `SalesOrderItems → BundleItems` **twice** (once for the child line via its own
+`bundleItemId`, once for its parent via the parent's `bundleItemId`) and compares
+`BundleItems.bundleId`. A mismatch, within the same order, is the corruption.
+
+## Detection query (read-only)
+
+Run against `Client_Compass`, read-only (via the TOGA Database Integration MCP). Confirm exact
+column names against the live schema before use:
+
+```sql
+SELECT child.salesOrderId,
+       child.id            AS childSalesOrderItemId,
+       biChild.bundleId    AS childKitBundleId,
+       parent.id           AS parentSalesOrderItemId,
+       biParent.bundleId   AS parentKitBundleId
+FROM   SalesOrderItems child
+JOIN   BundleItems      biChild  ON biChild.id  = child.bundleItemId
+JOIN   SalesOrderItems  parent   ON parent.id   = child.parentSalesOrderItemId
+JOIN   BundleItems      biParent ON biParent.id = parent.bundleItemId
+WHERE  child.bundleItemId IS NOT NULL
+  AND  child.bundleId     IS NULL          -- exclude legitimate nested child-bundles
+  AND  biChild.bundleId  <> biParent.bundleId;  -- child line attributed to the wrong kit
+```
+
+## Impact (verified on prod, read-only, 2026-07-08)
+
+| Schema | Corrupted orders | Corrupted line items |
+|---|---|---|
+| `Client_Compass` | **55** | **298** |
+| `Client_CompassCanada` | 0 | 0 |
+| `Client_Quad` | 0 | 0 |
+
+Compass Canada and Quad are **zero impact** — neither runs the multi-kit + shared-fee edit flow.
+**3 of the 55** Compass orders contain **nested bundles** — **SA119455, SA119508, SA133211** —
+and need more careful remediation than the other **52 flat** orders.
+
+## Remediation (NOT yet done — requires write access + review)
+
+- **Fix:** repoint each stray child line's `parentSalesOrderItemId` to **its own kit's primary**
+  in the same order (i.e. the primary whose `BundleItems.bundleId` equals the child line's
+  `BundleItems.bundleId`).
+- Handle the **3 nested-bundle orders separately** — do not batch them with the 52 flat orders.
+- **Why the code fix alone is insufficient:** the preventive frontend fix stops new corruption on
+  save but does not touch existing rows. On edit, `pairSalesOrderBundlesFromApi` rebuilds the
+  cart by grouping API lines on the (still-corrupted) `parentSalesOrderItem` identity, so old
+  orders keep rendering fees under the wrong kit until the DB rows are repaired.
+
+## Open questions — timeline is NOT conclusively the 2026-03-18 regression
+
+The corruption was initially attributed to the 2026-03-18 `uuid → bundleUuid` rename (commit
+e5115167). But **10 of the 55** impacted orders have `SalesOrders.dtUpdated` **before**
+2026-03-18. Two unresolved possibilities:
+1. `SalesOrders.dtUpdated` (the order **header**) is not the corruption clock — the edit flow
+   writes `SalesOrderItems` without bumping the header timestamp; or
+2. An **earlier** bundle-matching defect produced the same signature — the submit file's history
+   shows *"Improve matching logic"* (Jan 2026) and *"Fix item duplications"* (Oct 2025) — i.e. a
+   **recurring** bundle-matching bug class, not one 4-month-old bug.
+
+**Definitive check not yet run:** inspect `SalesOrderItems.dtUpdated` on the corrupted rows (not
+the header) to date the corruption precisely.
+
+## Systems involved
+
+- `toga2-commerce` edit-order submit path (`syncSalesOrderItemsFromLocalStorageCartToApi.ts`) — the cause.
+- `Client_Compass.SalesOrderItems` / `Client_Compass.BundleItems` — where the corruption lives.
+- TOGA Database Integration MCP (`toga_query` etc.) — read-only prod detection.
+
+## Change history
+- 2026-07-08 — Documented the cross-kit bundle-attribution corruption: the signature, a read-only
+  detection query, prod impact (Compass 55 orders / 298 line items; Canada 0; Quad 0; 3
+  nested-bundle orders SA119455 / SA119508 / SA133211 needing separate handling), the
+  preventive-vs-remediation distinction, and the unresolved timeline. Root cause is the
+  toga2-commerce `bundleUuid` submit bug (see the feature doc). Remediation not yet performed.
+  (apeterson)
+</content>

package/knowledge/clients/rate/INDEX.md

@@ -8,5 +8,5 @@
 | [Rate SAML SSO](features/saml-sso.md) | 2.0 | Rate uses Azure AD as its IdP (`login.rate.com`). | _underscore/Model/Rate/ClientAuthentication.php, saml/Controller/Index.php, toga2-view/src/hooks/useAuthenticationFlow.ts |
 | [Service Card Entitlement Display](features/service-card-entitlements.md) | 2.0 | Rate's home and services pages display one service card per purchased entitlement. | src/components/ServiceCard/ServiceCard.tsx, src/components/ServiceCard/index.ts, src/hooks/useBundleServices.ts, src/pages/Home/api/homeApi.ts, src/pages/Home/view/HomePage.tsx, src/pages/Home/viewModels/useHomePageViewModel.ts, src/pages/Services/view/ServicesPage.tsx, src/pages/Services/viewModels/useServicePageViewModel.ts |
 | [Rate Service-Purchase Confirmation Emails (Tech / Warranty)](features/service-purchase-emails.md) | 2.0 | When a Rate customer purchases a service, a confirmation email is sent. | _underscore/Model/Rate/Entitlement.php, worker2/Worker/Notification/EmailTemplate.php, dbchanges2/Client_Rate/2026-06-30a - Rate purchase email templates.sql |
-| [Rate Whole Home Warranty Per-Address Purchase Guard](features/whole-home-warranty-purchase-guard.md) | 2.0 | A customer may hold **one active Whole Home Warranty (WH) per validated address, globally** (across all borrowers). | _underscore/Model/Rate/Entitlement.php, _underscore/Model/Client/Address.php, dbchanges2/Client_Rate/2026-07-07a - WholeHomeWarrantyPerAddressGuard.sql |
+| [Rate Whole Home Warranty Per-Address Purchase Guard](features/whole-home-warranty-purchase-guard.md) | 2.0 | A customer may hold **one active Whole Home Warranty (WH) per validated address, globally** (across all borrowers). | _underscore/Model/Rate/Entitlement.php, _underscore/Model/Client/Address.php, dbchanges2/Client_Rate/2026-07-07a - WholeHomeWarrantyPerAddressGuard.sql, test/@Mark/Rate/verify_wholehome_per_address_guard.php |
 | [Rate](profile.md) | 2.0 | Rate is a mortgage/lending client. |  |

package/knowledge/clients/rate/features/whole-home-warranty-purchase-guard.md

@@ -6,12 +6,13 @@ project: _Underscore
 client: rate
 type: client-feature
 status: active
-updated: 2026-07-07
+updated: 2026-07-08
 owners: [mhammontree]
 files:
   - _underscore/Model/Rate/Entitlement.php
   - _underscore/Model/Client/Address.php
   - dbchanges2/Client_Rate/2026-07-07a - WholeHomeWarrantyPerAddressGuard.sql
+  - test/@Mark/Rate/verify_wholehome_per_address_guard.php
 related:
   - clients/rate/profile.md
   - clients/rate/features/aig-contract-creation.md
@@ -113,6 +114,17 @@ suggested-vs-entered when `success && address1`, and a "couldn't verify" toaster
 [address-validation feature](../../../2.0/apps/_underscore/features/address-validation.md) for the
 endpoint mechanics.
 
+## Verification
+
+A self-contained backend verification script lives at
+`test/@Mark/Rate/verify_wholehome_per_address_guard.php` (run via PHP CLI with `ENVIRONMENT`
+set, pinned to the real migrated **`Client_Rate`** schema — see the
+[2.0 backend-testing standard](../../../2.0/standards/backend-testing.md)). It applies
+`c_serviceAddressId` idempotently, seeds a token-tagged scratch WH graph (2 addresses / 2 items /
+2 active subscriptions / 2 entitlements), then exercises the pure helpers, the dedup matrix (via
+reflection on the private methods), and the `prePost` branches, cleaning up in a `finally`. The
+live carrier waterfall is opt-in via `RUN_LIVE=1` (defaults off). Verified **18/18 pass**.
+
 ## Gotchas / known issues
 
 - **TOCTOU on the uniqueness check (accepted).** The check-then-persist dedup is **not**
@@ -131,6 +143,9 @@ endpoint mechanics.
 
 ## Change history
 
+- 2026-07-08 — Added a backend verification script
+  (`test/@Mark/Rate/verify_wholehome_per_address_guard.php`, 18/18 pass against the migrated
+  `Client_Rate` schema) and a Verification pointer. (mhammontree)
 - 2026-07-07 — Built the WH per-address purchase guard (TRUE-79533): `prePost` on
   `_Model_Rate_Entitlement` hard-blocks invalid addresses and second active WH at the same
   normalized address (global), adopts the carrier-normalized address onto the payload, and

package/package.json

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