toga-ai 1.0.739 → 1.0.741

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

@@ -32,6 +32,7 @@
 | [_Model::save() vs raw _Query — no atomic conditional update](features/model-save-vs-query-atomic-update.md) | `_Model::save()` is a plain load-then-write ORM primitive and **cannot express an atomic conditional update** (an optimistic-concurrency / row-claim guard such | _underscore/Model.php, _underscore/Query.php, _underscore/Model/Rate/Subscription.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php, _underscore/Trait/Netsuite/SalesOrder.php, worker2/Worker/Netsuite/SalesOrder.php, worker2/Component/Forecast/SaleImport/SaleImport.php, worker2/Worker/Netsuite/Opportunity.php |
 | [NetSuite Sales Order sync — ship-to address, phone, and PO reference sourcing](features/netsuite-salesorder-address-phone-sync.md) | `_Trait_Netsuite_SalesOrder` is the **shared** sales-order importer composed into **22 client models** (every client on the dbchanges2 `netsuite` module). | _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Model.php, dbchanges2/_modules/netsuite/2026-08-10a - AddressPhoneNumberApiRoleAcl.sql |
+| [Outbound third-party API rate budget (_Component_Api_RateBudget) — designed + staged, NOT merged](features/outbound-api-rate-budget.md) | A **shared outbound rate budget for every third-party API** we call from 2.0 (ClickUp, NetSuite, FedEx, UPS, …): one small component plus one `Core` table, keye | _underscore/Component/Api/RateBudget/RateBudget.php, _underscore/Component/Api/Clickup/Clickup.php, _underscore/Route.php, _underscore/Query.php, dbchanges2/Core/2026-09-01a - Add ApiRateBudget table.sql, worker2/Worker/Clickup/Api.php |
 | [Legacy page meta (Page::meta) & context-scoped ClientRecordFieldSettings](features/page-meta-context-field-settings.md) | `_Model_Core_Page::meta()` is the **legacy** page-meta resolver behind `GET /pages/meta?slug=<slug>` — still the live path for `toga2-supply` and other pre-Surf | _underscore/Model/Core/Page.php, _underscore/Model/Client/TableView.php, toga2-supply/src/components/ui/Tables/PrimaryTable/PrimaryTable.tsx, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/formatTableData.tsx |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/Model.php, _underscore/Query.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php, api2/Controller/Index.php |
 | [Persona Name Translation (PersonaTranslations sidecar)](features/persona-name-translation.md) | Serves Persona **names** in multiple languages by adding a per-language **sidecar** table `PersonaTranslations`, reusing the platform's existing metadata-driven | _underscore/Model/Client/PersonaTranslation.php, dbchanges2/Client/2026-07-22b - PersonaTranslations.sql, dbchanges2/Core/2026-07-22a - PersonaTranslationsRecord.sql, dbchanges2/Client/2026-07-22c - PersonaTranslationsAcl.sql, dbchanges2/Client_CompassCanada/2026-07-22 - PersonaTranslationsFrench.sql, toga2-commerce/src/pages/Account/view/MySettingsView.tsx |

package/knowledge/2.0/apps/_underscore/features/outbound-api-rate-budget.md

@@ -0,0 +1,190 @@
+---
+title: Outbound third-party API rate budget (_Component_Api_RateBudget) — designed + staged, NOT merged
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: draft
+updated: 2026-09-02
+owners: [ajean]
+files:
+  - _underscore/Component/Api/RateBudget/RateBudget.php
+  - _underscore/Component/Api/Clickup/Clickup.php
+  - _underscore/Route.php
+  - _underscore/Query.php
+  - dbchanges2/Core/2026-09-01a - Add ApiRateBudget table.sql
+  - worker2/Worker/Clickup/Api.php
+related:
+  - ../architecture.md
+  - ../../worker2/features/creating-worker-actions.md
+  - ../../worker2/features/clickup-project-routing.md
+  - ./async-query-execution.md
+  - ./model-save-vs-query-atomic-update.md
+---
+
+## Summary
+
+A **shared outbound rate budget for every third-party API** we call from 2.0 (ClickUp,
+NetSuite, FedEx, UPS, …): one small component plus one `Core` table, keyed by a
+`bucketKey` string. It counts outbound calls per fixed 60-second window so we can *measure*
+our real request rate before enforcing any cap.
+
+**Status — nothing is shipped.** The component and its migration exist only as local staged
+files; they are not committed to `_underscore` or `dbchanges2`, and no PR contains them. They
+replace a rejected ClickUp-only design (533-line worker class + 106-line migration = 639 lines)
+that lives in the still-open PRs worker2 **#137** and dbchanges2 **#449**. Read this doc as a
+design record, not as live behavior.
+
+## Key files / entry points
+
+- `_underscore/Component/Api/RateBudget/RateBudget.php` — `_Component_Api_RateBudget`
+  (staged; 222 lines, ~103 lines of code).
+  - `take(string $bucketKey, int $limit): ?int` — **the entire public surface.** Increments the
+    current window's counter and returns the post-increment count, or `null` if the store is
+    unreachable. It never blocks, never sleeps, never throws on saturation.
+  - `prune()` — deletes old windows; call from an existing cron, never on the hot path.
+- `dbchanges2/Core/2026-09-01a - Add ApiRateBudget table.sql` — staged, 19 lines. Creates
+  `Core.ApiRateBudget`: `id`, `uuid`, `dtCreated`, `dtUpdated`, `bucketKey varchar(64)`,
+  `windowStart int UNSIGNED`, `requests int UNSIGNED`, with `UNIQUE KEY (bucketKey, windowStart)`.
+- Rejected predecessor (in PR #137 / #449, ClickUp-only): `worker2/Worker/Clickup/Api.php`.
+
+## How it works
+
+1. A caller about to hit a provider calls `take('clickup', $limit)`.
+2. The component upserts `(bucketKey, windowStart)` incrementing `requests`, then reads the row
+   back by primary key, and returns the count.
+3. The caller decides what to do with the number. **Counting and enforcement are deliberately
+   separate.**
+
+Design decisions worth keeping:
+
+- **One table, one class, keyed by `bucketKey`** (`'clickup'`, `'netsuite'`, `'fedex'`, `'ups'`).
+  Never a second per-provider table or class. The table lives in `Core/`, not `Team/`, because it
+  is platform infrastructure, not team tooling.
+- **Observe-only deployment is the point.** Run it for a week, read the real aggregate rate out of
+  `Core.ApiRateBudget`, then pick a threshold from measurement instead of guesswork. The
+  measurement *is* the test.
+- **Fixed 60s window, boundary computed by MySQL** (`FLOOR(UNIX_TIMESTAMP()/N)*N`) and **never by
+  PHP** — instance clock drift across the fleet would split the budget. Accepted trade-off: a burst
+  straddling a boundary is bounded at 2x nominal. If that ever matters, move to a 10s window and
+  `SUM()` the last 6 rows.
+- **Fail open.** If the store is unreachable: log once, return `null`, proceed with the call.
+  worker2 has **no DLQ and no redelivery**, so a fail-closed limiter outage would permanently
+  destroy production events — strictly worse than briefly exceeding a provider's cap.
+
+### Framework constraint: a cross-process counter needs its OWN DB alias, committed immediately
+
+This is the one piece of essential complexity carried over from the rejected design, and it
+applies to **any** shared counter or rollup in 2.0, not just this one.
+
+`_underscore/Route.php` opens a transaction on the **default** connection and holds it open until
+the job ends. So a counter written on the default alias is:
+
+1. **invisible to every other process** until the job ends — a fleet-wide total can never be read; and
+2. **a write lock held on one hot row** for up to the full 300s job budget — every worker that
+   touches the counter serialises behind it.
+
+The only escape is to register a **second connection under its own alias** and call
+`_Database::transactionCommit($alias)` immediately after the write. A "simplification" that drops
+the alias silently breaks correctness *and* adds a fleet-wide lock.
+
+### Why not the one-statement `LAST_INSERT_ID(expr)` upsert-and-read
+
+The tempting single statement —
+`... VALUES (… LAST_INSERT_ID(1)) ON DUPLICATE KEY UPDATE requests = LAST_INSERT_ID(requests + 1)`
+— is **not safe on a table with an `AUTO_INCREMENT id`**: `LAST_INSERT_ID()` returns the *new row
+id* on the INSERT path but the *assigned expression* on the UPDATE path. The 2.0 table standard
+mandates a leading `id AUTO_INCREMENT`, so the idiom would need empirical proof against the target
+MySQL 8 before use.
+
+**Decision:** upsert, then read the row back by primary key. One extra indexed lookup, obviously
+correct. The resulting read-after-write skew is **upward-only** under concurrency (another process
+may increment between our write and our read), so the number is conservative — it can cause an
+early yield but never an overrun.
+
+### Enforcement policy (once there is data) — never sleep-wait
+
+`MAX_EXECUTION_TIME_WORKER_ACTION` hard-caps any non-CronScheduler job at **300s**, and the
+JobScheduler watchdog only *writes the failure row* — it does not stop the PHP process. Sleeping to
+wait for budget therefore burns the cap and gets the job marked failed with **no retry and no DLQ**.
+See [Creating Worker Actions](../../worker2/features/creating-worker-actions.md).
+
+| Traffic class | Examples | Policy at the threshold |
+|---|---|---|
+| Bulk / sweep | sprint sync, stakeholder backfill, discovery | **Yield cleanly and reschedule the remainder.** Already chunked and resumable, so pausing costs nothing. This is where a cap gets real teeth. |
+| Event-driven / escalation | Sentry→ClickUp, webhooks, design review | **Proceed over budget, counted and alarmed.** Low volume, irreplaceable. |
+
+## Verified findings about ClickUp metering today
+
+- **The "500/min is worker2's deliberate half of ClickUp's 1000/min" premise is FALSE.** Both
+  `worker2/Worker/Clickup/Api.php` and the #449 migration assert that api2 and tools also call the
+  ClickUp API. Verified by grep across the `api2`, `tools` and `_underscore` checkouts: **zero**
+  references to `api.clickup.com` and **zero** `_Component_Api_Clickup::send()` calls in api2 or
+  tools. `tools` reads the `Team` database that worker2 populates; it does not call ClickUp.
+  worker2's realistic share is therefore **~900/min, not 500** — the limit must be re-derived with
+  the reviewer before any enforcement.
+- **~24 of ~116 ClickUp call sites would be unmetered** (measured on the merged tree via
+  `git merge-tree --write-tree` + grep): 92 metered, 6 raw `_Component_Api_Clickup::send()`, and 18
+  hand-built `api.clickup.com` endpoints — `Worker/Team/Sprint.php` (6),
+  `Worker/Netsuite/Opportunity.php` (6), `Worker/Sentry.php` (4),
+  `Worker/Netsuite/OpportunityStakeholderBackfill.php` (2). The **burstiest** loops (paginated
+  sprint sweeps, the stakeholder backfill) are among the unmetered ones, so a limiter as built
+  misses exactly the traffic most likely to breach a cap. **Call-site consolidation is the real
+  work** — any limiter is only as good as that.
+- **The rejected design's own enforcement test is blind to the biggest bypass.**
+  `TestNoDirectApiCalls()` greps only for `_Component_Api_Clickup::send(`, so it cannot see the 18
+  raw `api.clickup.com` sites, and it reports `RESULT: FAIL (2)` immediately post-merge because
+  `Worker/Monitor/Oneuptime.php` (5 unmetered calls) landed on `_production` after the branch was
+  cut. **A guard that passes while 18 bypasses exist manufactures false confidence.** This belongs
+  in CI as a ~10-line grep for `api.clickup.com` outside the component — not as a curl-invokable
+  worker action.
+
+## What was deliberately dropped from the rejected design
+
+45-vs-50 rolling-minute arithmetic, a 0.25s window-edge guard, batch reserve plus
+`register_shutdown_function` slot refunds, `beginBulk()`, `isBudgetTight()`, and a `CHECK`
+constraint hand-synced to a PHP constant. Rationale: that precision existed to guarantee
+≤495 requests per rolling minute — yet on saturation the limiter logged and **proceeded unmetered
+anyway**, so the exact bound was unenforceable by design and the arithmetic bought nothing.
+
+## Gotchas / known issues
+
+- `_Query::setQuery()` **executes non-SELECT queries immediately** — `new _Query($writeSql, $alias)`
+  runs the write eagerly, with no `execute()` call; `__destruct()` calls `execute()` as a backstop.
+  This is why any async flag must be set *before* `setQuery()`
+  (see [Asynchronous Query Execution](./async-query-execution.md)).
+- `_Query::fetchRow()` returns an **object**, not an array — `$row->requests`, never
+  `$row['requests']`. The affected-rows accessor is **`getAffectedRows()`** (there is no
+  `affectedRows()`). `fetchOne()` returns the first column of the first row, or `false` — the
+  cleanest single-value read.
+- **Security (location only):** `_underscore/Component/Api/Clickup/Clickup.php` declares a
+  hardcoded shared ClickUp workspace access token as a class constant next to `ENDPOINT`. Every
+  consumer authenticates as the same workspace identity, so per-consumer attribution and isolation
+  are impossible at the provider end — which also means a budget can never be attributed per caller
+  upstream. Needs rotation, a move to config/SSM, and a `/cso` pass. Already noted in
+  [ClickUp Design Sprint Automation](../../worker2/features/clickup-design-sprint-automation.md).
+
+## Ticket mapping (so the next reader does not conflate these)
+
+- **TRUE-80662 "ClickUp - Fix Project Hub Routing"** (Sprint 83, back-end review; reviewer Jeff
+  Cardinal) — contains nothing about rate limiting. The limiter arrived *inside* its PRs (#137,
+  #449). The outbound budget work has **no ticket of its own yet**.
+- **TRUE-80659** "formal rate limiting feature for the API … return a 429 with a Retry-Again
+  header" (filed by Jeff Cardinal; Backlog/On Bench, unassigned, unbuilt) — that is the **inbound**
+  429 + `Retry-After` feature, a **different** concern from this outbound budget.
+- **TRUE-4193** — an older per-IP **inbound** variant.
+
+## Change history
+- 2026-09-02 — Created. Designed `_Component_Api_RateBudget` + `Core.ApiRateBudget` (staged, not
+  merged) as a provider-agnostic replacement for the rejected 639-line ClickUp-only limiter;
+  recorded the false 500/min premise, the ~24 unmetered ClickUp call sites, the blind enforcement
+  test, the dedicated-alias requirement for any cross-process counter, and the no-sleep-wait
+  enforcement tiering. (ajean)
+
+## Related docs
+- [_underscore Framework Architecture](../architecture.md)
+- [Creating Worker Actions](../../worker2/features/creating-worker-actions.md) — the 300s cap
+- [ClickUp Project & Opportunity Multi-List Routing](../../worker2/features/clickup-project-routing.md) — PR #137's actual subject
+- [Asynchronous Query Execution](./async-query-execution.md)
+- [_Model::save() vs raw _Query](./model-save-vs-query-atomic-update.md)

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

@@ -3,7 +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 |
+| [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/api/helpers/formatBundlesForSalesQuoteZuCartinEditCart.ts, toga2-commerce/src/api/genericApi.ts, toga2-commerce/src/api/FilterApi.ts, toga2-commerce/src/api/translatedSearchApi.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

@@ -6,13 +6,17 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-08-27
-owners: ["apeterson"]
+updated: 2026-09-02
+owners: ["apeterson", "jcardinal"]
 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/api/helpers/formatBundlesForSalesQuoteZuCartinEditCart.ts
+  - toga2-commerce/src/api/genericApi.ts
+  - toga2-commerce/src/api/FilterApi.ts
+  - toga2-commerce/src/api/translatedSearchApi.ts
   - toga2-commerce/src/stores/useBundleBuilderZu.ts
   - _underscore/Model/Client/BundleItem.php
   - _underscore/Model/Client/SalesOrderItem.php
@@ -116,8 +120,28 @@ Also decided: **delete** the dead `where` clause in `BundleApi.tsx` rather than
 engine cannot prune nested children via `where` at all, and the clause could not express the
 fee / child-bundle exceptions even if it worked.
 
+## The bundle path never filters by catalog — it relays whatever item the API returns
+
+The storefront applies a `catalogId = 1` filter **only** on standalone item search
+(`src/api/genericApi.ts`, `FilterApi.ts`, `translatedSearchApi.ts`). The **bundle** path does not:
+`GET /v2/bundles/{uuid}` returns each kit line's `bundleItems.item.uuid`, and the cart submit relays
+that uuid verbatim (`src/api/helpers/formatBundlesForSalesQuoteZuCartinEditCart.ts`,
+`BundleView/api/BundleApi.tsx`). So the item a kit checkout POSTs is **whatever `BundleItems.itemId`
+resolves to on the server** — the browser never re-picks a catalog for it.
+
+**Consequence:** if a kit's `BundleItems.itemId` points at the wrong-catalog item, **every checkout
+of that kit silently POSTs the wrong item, and no frontend change fixes it — the data must be
+corrected.** This was the ongoing source of *new* bad orders after Compass USA's 2026-08-31 catalog
+fold: `BundleItems.itemId` for 434 active rows across 110 bundles still pointed at the Agilant
+catalog-2 twins, so each new kit checkout POSTed the Agilant item. Root cause + the
+restore-`BundleItems` fix:
+[Compass catalog-fold reversal](../../../clients/compass-usa/workflows/catalog-fold-reversal.md).
+
 ## Gotchas / known issues
 
+- **⚠ A folded/wrong `BundleItems.itemId` is invisible to the storefront's catalog filter.** The
+  catalog filter guards standalone search only; bundles relay the server's item uuid. Fix wrong-item
+  kits in the data (`BundleItems`), not in the frontend.
 - **⚠ 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
@@ -145,6 +169,13 @@ direct API write (`Logs.Api` request payload for that order).
 
 ## Change history
 
+- 2026-09-02 — Recorded that the storefront's `catalogId = 1` filter guards **standalone item
+  search only** (`genericApi.ts`, `FilterApi.ts`, `translatedSearchApi.ts`); the **bundle** path
+  relays whatever `bundleItems.item.uuid` `GET /v2/bundles/{uuid}` returns, so a kit checkout POSTs
+  whatever `BundleItems.itemId` resolves to server-side. A wrong-catalog `BundleItems.itemId`
+  therefore silently POSTs the wrong item and can only be fixed in data — this was the ongoing
+  source of new bad Compass orders after the 2026-08-31 catalog fold (434 rows / 110 bundles still
+  on the Agilant twins). (jcardinal)
 - 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

package/knowledge/2.0/apps/worker2/features/clickup-project-routing.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-31
+updated: 2026-09-02
 owners: [jcardinal, ajean]
 files:
   - worker2/Worker/Clickup/Project.php
@@ -17,6 +17,7 @@ related:
   - ./netsuite-opportunity-sync.md
   - ./clickup-connectivity-watchdog.md
   - ./clickup-subtask-activity.md
+  - ../../_underscore/features/outbound-api-rate-budget.md
 ---
 
 ## Summary
@@ -166,6 +167,14 @@ None — uniform across all clients (shared internal automation for Agilant's Cl
   needs **`taskCreated` on LS + A&M** and a **workspace-wide `taskMoved`**, registered via
   `RegisterHubGuardWebhooks()` (which skips any already covered to avoid double-delivery).
 
+- **PR #137 also carries a ClickUp rate limiter that is NOT part of this feature — and it was
+  rejected in review.** The open branch `fix/clickup-project-hub-routing` bundles a 533-line
+  `Worker/Clickup/Api.php` limiter (plus dbchanges2 #449) whose premise, coverage, and self-test are
+  all wrong: api2 and tools do **not** call ClickUp (verified by grep), ~24 of ~116 call sites stay
+  unmetered, and its `TestNoDirectApiCalls()` guard cannot see the 18 hand-built `api.clickup.com`
+  sites. Treat rate limiting as a separate subject with its own design —
+  [Outbound third-party API rate budget](../../_underscore/features/outbound-api-rate-budget.md).
+
 ## Diagnostics
 
 Read-only / setup actions, invoked via `curl -X POST https://worker.togahub.com/` with
@@ -176,6 +185,8 @@ Read-only / setup actions, invoked via `curl -X POST https://worker.togahub.com/
 `RESULT: PASS`), `RegisterOpportunityWebhook` and `RegisterHubGuardWebhooks` (one-time setup).
 
 ## Change history
+- 2026-09-02 — Noted that PR #137 bundles a rejected ClickUp rate limiter unrelated to routing, and
+  split that subject out to its own doc. No routing behavior changed. (ajean)
 - 2026-08-31 — Recorded the triage consequence of the hybrid split (read-only investigation, no code
   changed): worker-created opportunity tasks were observed **homed in `901111987451`
   "Quote/Proposal/SOW/MSA"** rather than the `901111987449` list they were POSTed to, with the mover

package/knowledge/2.0/apps/worker2/features/creating-worker-actions.md

@@ -17,6 +17,7 @@ related:
   - ../architecture.md
   - ./netsuite-opportunity-client-labels.md
   - ../../api2/features/api-payload-interceptors.md
+  - ../../_underscore/features/outbound-api-rate-budget.md
 ---
 
 ## Summary
@@ -232,6 +233,13 @@ production (2026-08-28, job `1075223`, a full `OpportunityStakeholderBackfill` d
 So an over-budget action loses its output **twice**: once to a false failure row, once to a dropped
 connection. Design for 300s.
 
+**Corollary — never sleep-wait for an external rate budget inside an action.** Pausing to wait for
+a third-party API slot burns the 300s cap, gets the job stamped failed by the watchdog, and there is
+no retry and no DLQ to recover it. Instead: **bulk/sweep** actions yield at the threshold and
+re-enqueue the remainder (they are already chunked and resumable, so pausing is free), while
+**event-driven/escalation** actions proceed over budget, counted and alarmed. See
+[Outbound third-party API rate budget](../../_underscore/features/outbound-api-rate-budget.md).
+
 ### Self-chunking: the pattern for work that cannot finish in one job
 
 An action that may exceed the budget works for a **sub-budget slice**, then **re-enqueues itself**
@@ -456,6 +464,9 @@ Rules: rename **both sides in one PR and one deploy**; grep every repo for the o
   commit-before-SQS transaction pattern that the worker relies on.
 
 ## Change history
+- 2026-09-02 — Added the corollary that an action must **never sleep-wait for a third-party API
+  rate budget** (it burns the 300s cap and the failure is unrecoverable — no retry, no DLQ); bulk
+  work yields and re-enqueues, event-driven work proceeds over budget counted and alarmed. (ajean)
 - 2026-09-02 — Added two authoring rules learned on the End Customer label work (worker2 PR #158/#159):
   **gate any code that names a column from a hand-applied dbchanges2 migration** on an
   `information_schema.COLUMNS` check memoised in a `static` (an ungated write fails the whole query

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

@@ -5,8 +5,8 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-09-01
-owners: [jcardinal, mhammontree, dfranks, bala]
+updated: 2026-09-02
+owners: [jcardinal, mhammontree, dfranks, bala, ajean]
 files: []
 related:
   - ../apps/_underscore/architecture.md
@@ -521,6 +521,33 @@ unapproved for 6 days because the approval was stamped with a dead user id. Prod
 See: clients/compass-usa/features/approval-decision-flow.md and
 clients/compass-usa/features/stranded-approval-reassignment.md
 
+### A cross-process counter or shared rollup MUST use its own DB alias, committed immediately
+
+`Route.php` opens a transaction on the **default** connection and holds it open until the request
+or job ends. So anything you write on the default alias for other processes to read is broken twice
+over:
+
+1. **Nobody else can see it** until your job ends — a fleet-wide total is unreadable by design.
+2. **You hold a write lock on one hot row** for up to the full 300s job budget, serialising every
+   other process that touches that counter.
+
+So any shared counter, rate budget, sequence, or rollup must:
+
+- register a **second connection under its own alias**, and
+- call `_Database::transactionCommit($alias)` **immediately after the write** — not at end of job.
+
+Removing the extra alias looks like a simplification. It is not: it silently breaks correctness and
+adds a fleet-wide lock.
+
+**Read the value back by primary key after the upsert.** Do not use the one-statement
+`LAST_INSERT_ID(expr)` upsert-and-read idiom on a table with an `AUTO_INCREMENT id` (which our
+table standard mandates): `LAST_INSERT_ID()` returns the new row id on the INSERT path but the
+assigned expression on the UPDATE path, so the result is path- and version-dependent. One extra
+indexed lookup is obviously correct. Under concurrency the read-after-write skew is upward-only,
+so the number is conservative.
+
+See [Outbound third-party API rate budget](../apps/_underscore/features/outbound-api-rate-budget.md).
+
 ## PHP
 
 ### PHP Tags
@@ -997,6 +1024,15 @@ See: 2.0/apps/worker2/features/cross-account-aws-access.md
 
 ## Change history
 
+- 2026-09-02 — Database/SQL: any **cross-process counter or shared rollup needs its own DB alias,
+  committed immediately**. `Route.php` holds a transaction open on the default connection until the
+  request/job ends, so a counter written there is invisible to every other process (a fleet-wide
+  total is unreadable) and holds a write lock on one hot row for up to the 300s job budget,
+  serialising the fleet. Register a second connection under its own alias and
+  `_Database::transactionCommit($alias)` right after the write. Also: read the value back by
+  primary key instead of the one-statement `LAST_INSERT_ID(expr)` upsert-and-read idiom — with the
+  mandated `AUTO_INCREMENT id` it returns the new row id on INSERT but the assigned expression on
+  UPDATE, so it is path- and version-dependent. (ajean)
 - 2026-09-01 — TRUE-81576. Three additions: (1) Security — never ship a hardcoded-credential
   fallback; the FedEx `initialize()` "production fallback" holds a live `client_id`/`client_secret`
   byte-identical to `api2/Config/production.ini`, so it must throw on missing `[fedex]` config, the

package/knowledge/INDEX.md

@@ -18,7 +18,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 75 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 76 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 58 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 25 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 15 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

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

@@ -22,7 +22,7 @@
 | [Compass Sales-Order Line-Number Renumbering (and why it hangs off the SO hooks)](features/sales-order-line-renumbering.md) | 2.0 | Compass sales-order lines must stay numbered **1..N with no gaps** after any add, edit, or delete — downstream MITS/PO linking reads `lineNumber` as an identity | _underscore/Model/Compass/SalesOrderItem.php, _underscore/Model/Compass/SalesOrder.php |
 | [Stranded Approval Reassignment (repointing approvals off dead duplicate Compass Users rows)](features/stranded-approval-reassignment.md) | 2.0 | A Compass employee who leaves and comes back after more than `CONTACT_UNLINK_GRACE_DAYS` (5) is **inserted as a brand-new `Users` row** by the PEOPLE importer i | _underscore/Model/Compass/ApprovalDecision.php, worker2/Worker/Client/Compass/ApprovalReassignment.php, worker2/Worker/Client/Compass/PeopleFile.php |
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |
-| [Compass USA — reversing the 199-item catalog fold (MITS outage recovery)](workflows/catalog-fold-reversal.md) | 2.0 | The **root cause** of the Compass MITS transmission outage (the `assetType`-NULL and duplicate-vendor symptoms) was an ad-hoc cross-client **duplicate-items mer | test/team/2.0 deployment/duplicate_items_merge_ALL_CLIENTS.sql, test/team/2.0 deployment/duplicate_items_merge_analysis.sql, worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/common_sync_togasupply.php |
+| [Compass USA — reversing the 199-item catalog fold (MITS outage recovery)](workflows/catalog-fold-reversal.md) | 2.0 | The **root cause** of the Compass MITS transmission outage (the `assetType`-NULL and duplicate-vendor symptoms) was an ad-hoc cross-client **duplicate-items mer | test/team/2.0 deployment/duplicate_items_merge_ALL_CLIENTS.sql, test/team/2.0 deployment/duplicate_items_merge_analysis.sql, 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, library/app/api/toga2.php, worker/crons/toga2/netsuite/common_sync_togasupply.php |
 | [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 |
 | [Granting a Compass user the same toga25-supply navigation as another user (role vs. SurfaceOverride)](workflows/granting-navigation-access.md) | 2.0 | "Give user X the same menu items user Y has" is the **navigation analog** of the recurring [bundle/persona grant](./granting-persona-bundle-access.md) request. | dbchanges2/Client_Compass/2026-08-12a - NavigationRoleGrants.sql, dbchanges2/Client_Compass/2026-02-25 - AgilantUsersViewAccess.sql, dbchanges2/Client_Compass/2026-08-11 - CompassODPViewVendorItemsAccess.sql, dbchanges2/Core/2026-08-12a - NavigationSurfaceSeed.sql |
 | [Granting a Compass user access to a bundle (persona grant) and the SuperUser role](workflows/granting-persona-bundle-access.md) | 2.0 | "Give user X sight of kit N" is a **recurring** Compass request, usually paired with "and make them a super user". | dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql |

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

@@ -6,7 +6,7 @@ project: Library
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-09-01
+updated: 2026-09-02
 owners: ["bala", "jcardinal"]
 files:
   - library/app/api/toga2.php
@@ -124,14 +124,18 @@ Plus `-1` / `-2` suffixed copies: items **2431, 2432, 2443, 2653**.
   span more than one catalog.** It matters only as a thing to re-check, because a part-number lookup
   with no catalog filter has **no ambiguity check on its exact-match branch**
   ([850 line-item resolution](odp-edi-850-item-resolution.md)).
-  **⚠ Unresolved tension — reconcile before relying on "partNumber is unique."** The
-  [2026-08-31 catalog-fold reversal](../workflows/catalog-fold-reversal.md) is recorded as having
-  folded **199 catalog-1 items into their catalog-2 Agilant canonical by `UPPER(partNumber)`**,
-  which requires those 199 to have shared a part number across the two catalogs pre-merge, and the
-  reversal restored them. That does not square with "zero part numbers span two catalogs" verified
-  the same day. Confirm on prod whether the restored catalog-1 twins carry **distinct** part numbers
-  (e.g. the `#B1H` / `-S` variant forms above) or genuinely-shared ones before treating table-wide
-  `partNumber` uniqueness as settled.
+  **Resolved: the twins carry DISTINCT part-number variants, so table-wide `partNumber` uniqueness
+  holds.** The Agilant `#ABA` form never equals the plain part number (e.g. `C40QYUC#ABA` vs
+  `C40QYUC`; `B7HJ2UC#ABA` vs `B7HJ2UC`), so any `UPPER(partNumber)` or partNumber-twin match
+  silently misses them. That is exactly why the
+  [catalog-fold reversal](../workflows/catalog-fold-reversal.md) ultimately mapped dupe→canon by
+  **primary key** from the pre-merge snapshot, never by part number, and why the `#ABA` PO-line
+  stragglers needed a manual VendorItem re-map. Only a history question remains (how the original
+  merge's `UPPER(partNumber)` partition folded pairs that do not share a part number); nothing
+  downstream depends on it. **⚠ Note:** the exact item ids ↔ catalog assignments in the
+  duplicate-pairs table above predate the 2026-08-31 fold and its reversal (which deleted then
+  restored catalog-1 items by their original snapshot ids), so re-read specific ids from current prod
+  before relying on them.
 
 ## Filtering by catalog: fine for *display*, never for *resolution*
 
@@ -196,6 +200,13 @@ children" rule:
 - **⚠ A NULL `catalogId` is a real state** (27 items in prod, 22 ODP `VendorItems` point at such
   items). Anything joining through `Catalogs` **drops those rows silently** — an inner join to
   `Catalogs` is itself a filter.
+- **⚠ `BundleItems.itemId` is a silent catalog-resolution consumer — the storefront never
+  re-catalogs it.** The `toga2-commerce` storefront relays whatever item `GET /v2/bundles/{uuid}`
+  returns; its `catalogId = 1` filter guards standalone item search only, never bundles. So a kit
+  whose `BundleItems.itemId` points at the wrong-catalog twin makes **every checkout POST the wrong
+  item** (434 rows / 110 bundles after the 2026-08-31 fold). Fix in data, not the frontend. See
+  [catalog-fold reversal](../workflows/catalog-fold-reversal.md) and
+  [bundle item visibility & selectability](../../../2.0/apps/toga2-commerce/features/bundle-item-visibility-and-selectability.md).
 - **⚠ `isFulfillable` is born on the catalog-2 (Agilant) item** and propagates to the client-facing
   copy; the flag's home catalog is not an accident. See
   [isFulfillable data quality & the type rule](isfulfillable-data-quality-and-type-rule.md).
@@ -212,6 +223,15 @@ children" rule:
   [catalog-fold reversal](../workflows/catalog-fold-reversal.md).
 
 ## Change history
+- 2026-09-02 — **Resolved the flagged "distinct vs shared partNumber" tension**: the Agilant twins
+  carry **distinct** part-number variants (the `#ABA` form ≠ the plain part number, e.g.
+  `C40QYUC#ABA` vs `C40QYUC`), so table-wide `partNumber` uniqueness holds and the catalog-fold
+  reversal maps dupe→canon by **primary key**, never by part number (part-number matching misses the
+  `#ABA` stragglers). Flagged that exact item ids ↔ catalog assignments in the duplicate-pairs table
+  predate the fold+reversal and should be re-read from prod. Added `BundleItems.itemId` as a silent
+  catalog-resolution consumer — the storefront relays the bundle item uuid with no catalog filter, so
+  a folded `BundleItems.itemId` (434 rows / 110 bundles) POSTs the wrong item on every kit checkout
+  until the data is fixed. (jcardinal)
 - 2026-09-01 — Folded in the **customer → catalog rule** (`customerId = 2` → catalog 1, everyone
   else → catalog 2; verified 182,787 vs 1 pre-merge) and the mandatory `customerId` scope on any
   catalog re-point (an unscoped one moved 687 Office-Depot lines). Added that the NetSuite sync

package/knowledge/clients/compass-usa/features/mits-po-transmission-to-vendors.md

@@ -5,8 +5,8 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-07-14
-owners: ["rgirish", "bala"]
+updated: 2026-09-02
+owners: ["rgirish", "bala", "jcardinal"]
 files:
   - 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
@@ -14,6 +14,8 @@ files:
 related:
   - mits-po-to-so-item-linking.md
   - order-lifecycle-and-data-integrity.md
+  - item-catalogs-and-duplicate-items.md
+  - ../workflows/catalog-fold-reversal.md
 ---
 
 ## Summary
@@ -87,6 +89,19 @@ Compass Canada has a parallel `compasscanada/workflow/2_transmit_...` keyed on
 `CUSTOMER_ID__COMPASS_CANADA`.
 
 ## Gotchas / known issues
+- **⚠ Everything transmitted is sourced from the `VendorItem` the PO line points at — a
+  wrong-catalog `vendorItemId` sends the wrong SKU, wrong cost, AND the wrong channel.** The vendor
+  SKU and the cXML-vs-EMAIL routing come entirely from the `VendorItem` that
+  `PurchaseOrderItems.vendorItemId` references (with `PurchaseOrderItems.cost` for price). So a PO
+  line pointing at an **Agilant** VendorItem instead of the Office-Depot one transmits Agilant's
+  **internal SKU** and **wrong cost**, and — because that VendorItem carries **no
+  `overridePoSubmissionIntegrationId`** — falls back to the vendor's default **EMAIL** integration
+  instead of **cXML**. Verified in the legacy `Logs.API`: good order **SA136666** went **cXML** to
+  `b2b.odpbusiness.com` with `SupplierPartID 5775600` / `UnitPrice 945.17`; bad order **SA136846**
+  went **email** with `C40QYUC#ABA` / `$61`. This was a downstream symptom of the 2026-08-31 catalog
+  fold (a folded PO line resolved to the Agilant twin) — root cause and reversal:
+  [catalog-fold reversal](../workflows/catalog-fold-reversal.md);
+  [two-catalog item model](item-catalogs-and-duplicate-items.md).
 - **Item-less PO is silently marked submitted without being sent (the "logs show not sent
   but dtSubmitted is set" symptom).** The `dtSubmitted = NOW()` UPDATE runs **unconditionally
   after** the per-integration `foreach`, not inside it. If a PO has **zero
@@ -109,6 +124,12 @@ Compass Canada has a parallel `compasscanada/workflow/2_transmit_...` keyed on
   `dtSubmitted` stamped without a log (separate, previously-observed failure mode).
 
 ## Change history
+- 2026-09-02 — Recorded that cron 2 sources the vendor **SKU, cost, and cXML-vs-EMAIL routing**
+  entirely from the `VendorItem` at `PurchaseOrderItems.vendorItemId` (plus `PurchaseOrderItems.cost`),
+  so a PO line folded onto an **Agilant** VendorItem transmits Agilant's internal SKU, the wrong
+  cost, and — lacking `overridePoSubmissionIntegrationId` — drops from cXML to the default EMAIL
+  channel. Evidence: good `SA136666` cXML `SupplierPartID 5775600` / `945.17`; bad `SA136846` email
+  `C40QYUC#ABA` / `$61`. Downstream symptom of the 2026-08-31 catalog fold. (jcardinal)
 - 2026-07-14 — Fixed the emailed-PO PDF for both US Compass and Compass Canada: line-item
   rows now advance by their measured wrapped height (long descriptions no longer overwritten),
   and pagination is height-aware (a real 21-item PO went from a broken 17-page PDF to a clean

package/knowledge/clients/compass-usa/features/mits-sales-order-transmission-alerting.md

@@ -5,7 +5,7 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-08-31
+updated: 2026-09-02
 owners: ["dfranks", "bala", "jcardinal"]
 files:
   - worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php
@@ -125,7 +125,12 @@ backlog (0 new, several >24h, one ~20 days old).
    order**. This was the active blocker (e.g. item `4U555A-S`; ~10 distinct NULL-assetType
    items blocked 9 of 11 pending orders).
 2. **HTTP 403 `SalesOrder:Exists`** — MITS already created the order on a prior attempt, but
-   our side never recorded `c_dtTransmittedToCompass`, so the cron **retries it forever**.
+   our side never recorded `c_dtTransmittedToCompass`, so the cron **retries it forever**. **Now
+   handled (2026-09-02):** on a 403 `SalesOrder:Exists` the cron stamps
+   `SalesOrders.c_dtTransmittedToCompass`, writes a `Record`, and **continues** to the next order
+   instead of throwing — so an already-created order no longer starves the queue. Root cause of the
+   original loop (why we never stamped the first time) was the `App_ApiTransaction` decode fatal —
+   see the gotcha below.
 
 **Deeper root cause of the 2026-08-31 outage — a wrong catalog merge, not just missing data.**
 The NULL-assetType items were largely created by an ad-hoc cross-client dedup that folded
@@ -170,7 +175,19 @@ pages even when the count is under threshold. See
   console, pushed to ClickUp, and emailed — so the payload was deliberately removed. Alerts here
   name the order, not the person. (This is precisely what Canada still does wrong.)
 - **The MITS crons hold their API credentials inline in the file.** Treat both files as
-  secret-bearing when copying snippets anywhere (tickets, PR bodies, knowledge docs).
+  secret-bearing when copying snippets anywhere (tickets, PR bodies, knowledge docs). The two
+  hardcoded MITS credentials live inline in
+  `1_transmit_compass_sales_orders_to_mits.php` — note their location, never paste the values.
+- **⚠ 1.0 `App_ApiTransaction` built with `ENCODE_JSON` returns an ALREADY-DECODED object — do
+  NOT `json_decode()` it.** A transaction constructed with `App_ApiTransaction::ENCODE_JSON` hands
+  back a decoded object from `execute()`, not a JSON string. Calling `json_decode()` on it raises a
+  PHP 7.2 `"expects parameter 1 to be string, object given"` warning, which `App_Error` escalates to
+  a **FATAL**. In `1_transmit_compass_sales_orders_to_mits.php` that fatal fired **after** the order
+  transmitted to MITS but **before** stamping `c_dtTransmittedToCompass` — producing a ~42-order
+  backlog and the endless `SalesOrder:Exists` retry loop above (MITS kept the created order, we
+  never recorded it). Correct pattern:
+  `$decodedResp = is_string($resp) ? json_decode($resp) : $resp;`. This is a reusable 1.0 footgun,
+  not a Compass-only one — any `App_` code that `json_decode()`s an `ENCODE_JSON` response hits it.
 - **The transmit item query's `GROUP BY SalesOrderItems.id` hides false "duplicates."** In
   `1_transmit_compass_sales_orders_to_mits.php` (~L178-251, `GROUP BY` at L247) the
   `GROUP BY SalesOrderItems.id` collapses the `LEFT JOIN VendorItems` / `LEFT JOIN
@@ -193,6 +210,15 @@ pages even when the count is under threshold. See
   when this issue next fires. Watch that run rather than assuming it works.
 
 ## Change history
+- 2026-09-02 — **Shipped HTTP 403 `SalesOrder:Exists` handling** in
+  `1_transmit_compass_sales_orders_to_mits.php`: on that response the cron now stamps
+  `c_dtTransmittedToCompass`, writes a `Record`, and continues instead of throwing forever (which
+  had starved the `ORDER BY RAND()` queue). Recorded the **root cause** of the loop — a 1.0
+  `App_ApiTransaction` built with `ENCODE_JSON` returns an **already-decoded object**, so a
+  `json_decode()` on it raises a PHP 7.2 warning that `App_Error` escalates to a **FATAL** *after*
+  transmit but *before* the stamp, producing a ~42-order backlog and the endless retry loop; the
+  fix is `is_string($resp) ? json_decode($resp) : $resp`. Flagged it as a reusable 1.0 footgun. Also
+  noted the two hardcoded MITS credentials' location. (jcardinal)
 - 2026-09-01 — Traced the 2026-08-31 outage to its **deeper root cause**: an ad-hoc
   cross-client dedup folded Compass's 199 catalog-1 store items into their Agilant canonical, so
   order lines resolved to unclassified Agilant items (HTTP 400) and their fused VendorItems

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

@@ -19,7 +19,7 @@ project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-09-01
+updated: 2026-09-02
 owners: [jcardinal, bala, tcox, apeterson, dfranks, akhokhani]
 files: []
 related:
@@ -92,6 +92,12 @@ separate, related client (see its own profile).
   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).
+- **⚠ A folded `BundleItems.itemId` makes the storefront POST the wrong-catalog item (2026-09-02).**
+  The storefront relays whatever item `GET /v2/bundles/{uuid}` returns and filters `catalogId = 1`
+  only on standalone search, never on bundles — so after the 2026-08-31 catalog fold, 434 kit-line
+  rows across 110 bundles still on the Agilant twins produced a fresh bad order on every kit
+  checkout. Fixed by restoring `BundleItems` in the complete catalog-fold reversal (fix is data, not
+  frontend): [catalog-fold reversal](workflows/catalog-fold-reversal.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/catalog-fold-reversal.md

@@ -5,17 +5,20 @@ project: _Underscore
 client: compass-usa
 type: workflow
 status: active
-updated: 2026-09-01
+updated: 2026-09-02
 owners: ["jcardinal", "bala"]
 files:
   - test/team/2.0 deployment/duplicate_items_merge_ALL_CLIENTS.sql
   - test/team/2.0 deployment/duplicate_items_merge_analysis.sql
   - 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
   - library/app/api/toga2.php
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
 related:
   - ../features/item-catalogs-and-duplicate-items.md
   - ../features/mits-sales-order-transmission-alerting.md
+  - ../features/mits-po-transmission-to-vendors.md
+  - ../../../2.0/apps/toga2-commerce/features/bundle-item-visibility-and-selectability.md
   - ../../../1.0/apps/worker/workflows/netsuite-duplicate-items-dedup.md
 ---
 
@@ -59,48 +62,116 @@ NULL-catalog junk items** and **199 duplicate-Agilant items** (from the NetSuite
 inventory-adjustment item-create bug). **Only the 199 catalog-1 → catalog-2 folds were the
 damage.**
 
-**⚠ Open contradiction — not resolved, do not assume either side.** Folding by
-`UPPER(partNumber)` requires those 199 pairs to have **shared a part number across catalogs**
-pre-merge, and the reversal restored them. But a prod check of `Client_Compass` on **2026-09-01**
-found **zero part numbers duplicated at all, and zero spanning more than one catalog**. Both
-statements cannot be true of prod today. Re-check on prod whether the restored catalog-1 twins
-carry **distinct** part-number variants (the `#B1H` / `-S` forms) or genuinely-shared ones before
-relying on either the 199 figure or table-wide `partNumber` uniqueness. Same flag from the other
-side: [two-catalog item model](../features/item-catalogs-and-duplicate-items.md).
-
-## The reversal playbook (durable)
-
-1. **Restore a pre-merge snapshot as a scratch DB** — e.g. `Client_Compass_20260831_120000`
-   (taken ~12:00, before the ~12:43 merge). **Validate it is pre-merge**: catalog-1 twins
-   present, `customerId = 2` lines on catalog 1.
-2. **Rebuild the merge's damage map from the snapshot** — the Agilant-preferred ranking above,
-   filtered to `dupe.catalog = 1 AND canon.catalog = 2` = the 199.
-3. **Write a set-based, single-transaction, FK-checks-ON, NO `IGNORE`, COMMIT-left-commented
-   script** (`SNAP_DB.` / `TARGET_DB.` qualifiers) that:
-   - Restores the 199 Compass `Items` + their `VendorItems` / `VendorItemCosts` **by id**
-     (`NOT EXISTS` guard).
-   - **Re-points current `customerId = 2` `SalesOrderItems`** from the Agilant canonical back
-     to the Compass twin — **on CURRENT data, not a uuid-restore.** The sync re-created order
-     lines with **new uuids**, so restoring snapshot lines by uuid **collided 1062** on
-     `UNIQUE(salesOrderId, lineNumber)`.
-4. **Rehearse on a same-day full prod clone** — this run: ~49,267 re-points, 199 items, 0
-   orphans, held items 0-missing-assetType / 0-multi-vendor.
-5. **Apply to prod with a pre-run backup.** Result: queue drained to 0 pending; all
-   `customerId = 2` lines back on catalog 1.
-
-**CTO review gated this** (rehearse-on-clone, fail-loud, customer-scoped, tenant-locked).
+**Part-number matching is unreliable here — the reversal maps dupe→canon by PRIMARY KEY, not
+part number.** The Agilant twins carry **distinct** part-number variants, not shared ones: the
+`#ABA` form does not equal the Compass part number (`C40QYUC#ABA` = item 2216 vs Compass
+`C40QYUC` = 2157; `B7HJ2UC#ABA` = 2215 vs Compass `B7HJ2UC` = 2160). So any `UPPER(partNumber)`
+or partNumber-twin re-point silently misses them, which is why the complete reversal keys off the
+snapshot's own primary keys (below) and table-wide `partNumber` uniqueness still holds on prod.
+(Left open only as history: how the original merge's `UPPER(partNumber)` partition folded pairs
+that do not share a part number — the reversal does not depend on the answer, because it never
+matches on part number.) Same note from the other side:
+[two-catalog item model](../features/item-catalogs-and-duplicate-items.md).
+
+## The first reversal was INCOMPLETE — it left 10 tables folded
+
+The earlier reversal (`compass_twocatalog_fix.sql`) restored `Items` / `VendorItems` /
+`VendorItemCosts` and re-pointed **`SalesOrderItems`** — but **only the `customerId = 2` slice**
+of those. It **left folded** every other table the merge touched: `customerId = 1` and
+`customerId = 3` `SalesOrderItems` (~50k rows), `ItemFeatures`, `ItemImages`, **`BundleItems`**,
+`Personas_Items`, `Units`, `ItemPrices`, `ItemMedia`, `AssortmentItems`, and `InvoiceItems` — 10
+tables still pointing at the Agilant canonical.
+
+**Durable rule: a fold reversal MUST cover EVERY table the merge enumerates.** Restoring the
+parent `Items` and re-pointing one child table is not a reversal. The
+`duplicate_items_merge_ALL_CLIENTS.sql` block lists **38** reference points — read it as the
+checklist:
+
+- **24 `itemId` tables**,
+- **`Entitlements.saleItemId`**,
+- **3 `vendorItemId` tables** — `PurchaseOrderItems`, `VendorItemCosts`, `Personas_VendorItems`,
+- **10 `unitId` tables**.
+
+Anything on that list still resolving to a canonical is unreversed. The left-folded `BundleItems`
+in particular was the ongoing source of *new* bad orders (see below).
+
+## The complete reversal (durable method)
+
+Restore **every** fold-affected row from the pre-merge snapshot
+`Client_Compass_20260831_120000` (taken ~12:00, before the ~12:43 merge) **BY PRIMARY KEY** — not
+by part-number twin matching (the `#ABA` variants make that unreliable, see above). The snapshot's
+own primary keys are the only dependable dupe→canon mapping. **Validate the snapshot is pre-merge
+first** (catalog-1 twins present, `customerId = 2` lines on catalog 1). Then, in a single
+transaction, FK-checks-ON, **no `UPDATE IGNORE`**, COMMIT left commented (`SNAP_DB.` / `TARGET_DB.`
+qualifiers):
+
+1. **Parents — full-row restore.** `Items`, `VendorItems`, `VendorItemCosts`, `Units` restored
+   whole from the snapshot by id (`NOT EXISTS` guard).
+2. **Children — FK-column-only restore.** For every child table on the merge's 38-point list,
+   restore **only the folded FK column** to its snapshot value, keyed by the child row's own PK.
+   (Verified zero non-FK drift, so nothing else is touched.)
+3. **Post-snapshot "broken-window" rows** — rows created **after 2026-08-31 12:00** that are not
+   in the snapshot are re-pointed canon→dupe on **current** data, **scoped `customerId = 2`** (the
+   uuid-collision and customer-scope rules below still apply — the sync re-created order lines with
+   **new uuids**, so a uuid-restore collided 1062 on `UNIQUE(salesOrderId, lineNumber)`).
+4. **Verify byte-for-byte.** This run: **0** rows still folded across all **38** tables and **0**
+   byte mismatches over **208,845** compared rows.
+
+**Rehearse on a same-day full prod clone, then apply with a pre-run backup. CTO review gated the
+approach** (rehearse-on-clone, fail-loud, customer-scoped, tenant-locked).
+
+### Stragglers: `#ABA`-variant PO lines need a manual VendorItem re-map
+Because the `#ABA` twins share no part number, neither the merge's part-number map nor a
+partNumber-twin re-point catches PurchaseOrder lines sitting on them. These were fixed by an
+**explicit VendorItem mapping**, scoped to **pending `customerId = 2` PO lines**, then clearing
+`PurchaseOrders.dtSubmitted` so the PO re-transmits: VendorItem **3845 → 3597** @ `945.17`,
+VendorItem **3884 → 3600** @ `1627.38`. Why a mis-mapped PO line transmits the wrong SKU + cost
+and drops to EMAIL rather than cXML:
+[MITS PO transmission to vendors](../features/mits-po-transmission-to-vendors.md).
+
+## The folded `BundleItems` was the storefront's ongoing bad-order source
+`BundleItems.itemId` (kit definitions) still pointed at the Agilant catalog-2 twins — **434 active
+rows across 110 bundles**. The `toga2-commerce` storefront does **not** choose a catalog: it
+relays whatever item uuid `GET /v2/bundles/{uuid}` returns (`bundleItems.item.uuid`). The
+`catalogId = 1` filter runs **only** on standalone item search (`genericApi.ts`, `FilterApi.ts`,
+`translatedSearchApi.ts`), **never** on bundles. So a folded `BundleItems.itemId` makes **every new
+checkout of that kit POST the Agilant item** — a fresh wrong-catalog order each time. **The fix is
+data (restore `BundleItems`); the frontend needs no change.** Storefront-side detail:
+[bundle item visibility & selectability](../../../2.0/apps/toga2-commerce/features/bundle-item-visibility-and-selectability.md).
+
+## The NetSuite→TOGa sync is NOT the source of new cust-2 bad orders (suspect ruled out)
+The 1.0 NetSuite→TOGa TOGaSupply sync (`worker/crons/toga2/netsuite/`,
+`App_Api_Toga2::syncSalesOrderFromNetsuite`, `library/app/api/toga2.php` ~L752) writes **only the
+Agilant `customerId = 3` sales order** for Compass — it **pins** `locationId = 615286` and
+`customerId = 3` (~L807-809) and cannot write or re-point a `customerId = 2` (Compass storefront)
+order. **Stopping it fixed nothing.** The real ongoing source of new bad orders was the folded
+`BundleItems` (above), not the sync — this corrects the earlier "the sync re-points cust-2 lines
+back to Agilant / stop it first" concern. (The sync still *creates items* in catalog 2 — that is
+the original duplicate-item source, see the two-catalog model.)
+
+Context — the Compass order chain is up to **four** SalesOrders, linked by the
+`SalesOrders_PurchaseOrders` / `PurchaseOrders_SalesOrders` bridge tables: Compass storefront SO
+(`cust 2`) → MITS PurchaseOrder → ODP SO (`cust 1`) → Agilant/NetSuite SO (`cust 3`). The catalog
+rule still holds: `cust 2` → catalog 1; `cust 1` and `cust 3` → catalog 2.
 
 ## Critical rules
 
+- **Cover EVERY table the merge lists — restore by PRIMARY KEY, not by part number.** The merge
+  enumerates 38 reference points (24 `itemId` + `Entitlements.saleItemId` + 3 `vendorItemId` +
+  10 `unitId`); a reversal that touches only `Items` + one child table is incomplete (the first
+  attempt left 10 tables folded). `#ABA` twins share no part number, so partNumber matching misses
+  them — map dupe→canon from the snapshot's own PKs.
 - **Scope every catalog re-point by `customerId`.** An unscoped
   `UPDATE ... WHERE itemId = <agilantId>` wrongly moved **687 Office-Depot lines** onto the
   Compass item and had to be corrected.
-- **Re-point on CURRENT data, never restore order lines by uuid** — the sync minted new uuids,
-  so a uuid-restore collides on `UNIQUE(salesOrderId, lineNumber)` (1062).
-- **Stop the Compass NetSuite sync first.** The sync re-creates Compass order lines on Agilant
-  items, so the reversal is only durable if the sync is stopped; re-enabling risks re-pointing
-  new/re-synced orders back to Agilant (2 lines seen after a test re-enable). See the
-  [two-catalog item model](../features/item-catalogs-and-duplicate-items.md).
+- **Re-point post-snapshot rows on CURRENT data, never restore order lines by uuid** — the sync
+  minted new uuids, so a uuid-restore collides on `UNIQUE(salesOrderId, lineNumber)` (1062).
+- **The NetSuite→TOGa sync is NOT the ongoing source of new cust-2 bad orders — the folded
+  `BundleItems` is.** `syncSalesOrderFromNetsuite` pins `customerId = 3` for Compass and writes
+  only the Agilant-tier SO, so it cannot re-point a cust-2 storefront line; stopping it changes
+  nothing. Restore `BundleItems` to stop new wrong-catalog checkouts. (The sync still *creates
+  items* in catalog 2 — that is the original duplicate-item source, see the
+  [two-catalog item model](../features/item-catalogs-and-duplicate-items.md).)
 - **Never `UPDATE IGNORE` + delete-leftover for a catalog operation** — it permanently deletes
   collision rows and cannot be reversed. Use FK-checks-ON, fail-loud, single transaction.
 
@@ -136,6 +207,23 @@ catalog-1 items were folded into catalog-2 **AND** storefront/transmit depends o
 NULL-`assetType` order lines alone are **not** damage (Prudential and Quad show that as normal).
 
 ## Change history
+- 2026-09-02 — **Completed the reversal and root-caused the rest of the incident.** Recorded that
+  the first reversal was **incomplete** — it restored `Items`/`VendorItems`/`VendorItemCosts` and
+  re-pointed only `customerId = 2` `SalesOrderItems`, leaving **10 tables** folded (cust-1/cust-3
+  `SalesOrderItems` ~50k, `ItemFeatures`, `ItemImages`, `BundleItems`, `Personas_Items`, `Units`,
+  `ItemPrices`, `ItemMedia`, `AssortmentItems`, `InvoiceItems`). Added the **cover-every-table**
+  rule (the merge lists 38 reference points: 24 `itemId` + `Entitlements.saleItemId` + 3
+  `vendorItemId` + 10 `unitId`) and the **complete method**: restore every fold-affected row from
+  the pre-merge snapshot **by PRIMARY KEY** (part-number matching fails because `#ABA` twins carry
+  distinct part numbers), parents full-row / children FK-column-only, post-snapshot rows re-pointed
+  cust-2 on current data; verified 0 folded across 38 tables / 0 byte mismatches over 208,845 rows.
+  Recorded the folded **`BundleItems`** (434 rows / 110 bundles) as the storefront's ongoing
+  bad-order source (toga2-commerce relays the bundle item uuid with no catalog filter — fix is
+  data), the **`#ABA` straggler** manual VendorItem re-map (3845→3597 @945.17, 3884→3600 @1627.38,
+  scoped cust-2 pending PO lines + clear `dtSubmitted`), and that the **NetSuite→TOGa sync is not**
+  the source of new cust-2 orders (it pins `customerId = 3` + `locationId = 615286`, writes only the
+  Agilant SO) — correcting the earlier "stop the sync first" rule. Resolved the part-number
+  contradiction for the reversal (maps by PK, never by partNumber). (jcardinal)
 - 2026-09-01 — Flagged (did **not** resolve) the contradiction between this doc's 199
   shared-`UPPER(partNumber)` catalog-1→catalog-2 folds and the same-day prod verification that zero
   Compass part numbers span two catalogs; mirrored from the item-catalogs doc so it is visible from

package/package.json

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