toga-ai 1.0.552 → 1.0.553

package/knowledge/2.0/apps/_underscore/features/error-reporting-issue-event.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-10
+updated: 2026-08-11
 owners: ["dfranks", "jcardinal", "mhammontree", "ajean", "bala"]
 files:
   - _underscore/Error.php
@@ -33,6 +33,7 @@ related:
   - ../../../1.0/apps/tools/features/errors-curation-console.md
   - ../../../1.0/apps/library/features/error-capture-1-0.md
   - ../../api2/features/v2-api-error-codes.md
+  - ../../api2/features/request-logging.md
   - ../../dbchanges2/architecture.md
   - ../../../../1.0/apps/library/features/http-500-error-monitor.md
 ---
@@ -362,6 +363,19 @@ WHERE issueId = <issue.id> AND eventNumber = <n>;
   tenant that has gone quiet auto-resolves; check `dtLastOccurred` against the tenant's traffic
   before believing it (see
   [error-issue auto-resolution](../../worker2/features/error-issue-auto-resolution.md)).
+- **Tell an AUTO-close from a real fix by the columns, not the status.** `dtAutoResolved`
+  populated **and `isManaged = 0`** means the frequency-decay cron closed it after its quiet
+  window — **nobody looked at the code**. On the listing that is visually identical to a defect a
+  human fixed, and it will silently reopen on the next occurrence. Before you accept "already
+  resolved", confirm a code or config change actually shipped. (This diverted a production
+  investigation on 2026-08-11.)
+- **`Event.context` carries the per-occurrence request identity** — `requestMethod`,
+  `requestPath`, **`transactionId`**, `referer`, `userAgent`, `instanceId`, the Elastic Beanstalk
+  environment and the PHP version. `transactionId` is the field that collapses a burst of
+  near-identical occurrences back into the **one** user action that caused them, because apiproxy
+  retries a 5xx across regions under a single transaction id — see
+  [api2 request logging](../../api2/features/request-logging.md). Read occurrence counts through
+  it or you will overstate user impact.
 - The **1.0 alert surface** that fires on these is
   [App_SystemMonitor_500Error](../../../../1.0/apps/library/features/http-500-error-monitor.md) — its
   "Error Type" is a fallback literal with **zero** diagnostic value, which is why this recipe
@@ -617,6 +631,15 @@ clientUserId). **Neither was built.** As built instead:
 
 ## Change history
 
+- 2026-08-11 — Sharpened the `error.id` lookup recipe from a production incident investigation
+  (Compass, api2 500s): **`status = 'RESOLVED'` with `dtAutoResolved` set and `isManaged = 0` is a
+  cron auto-close after a quiet window, not a fix** — it is indistinguishable from a real fix on
+  the listing and reopens on the next occurrence, so verify a code/config change actually shipped
+  (this misdirected the investigation once). Also recorded what `Event.context` actually carries
+  per occurrence (`requestMethod`, `requestPath`, `transactionId`, `referer`, `userAgent`,
+  `instanceId`, EB environment, PHP version) and that **`transactionId` is the field that collapses
+  an apiproxy cross-region retry storm back into one user action** — occurrence counts read
+  without it overstate impact. No code change. (bala)
 - 2026-08-10 — Added the **`error.id` lookup recipe** (`Logs.Api.responsePayload` → `Logs.Issue`
   by `reference` → `Logs.Event` by `eventNumber` for the tenant), because in production `error.id`
   is the **only** handle an api2 500 gives you — `message`/`trace` are debug-mode-gated so the

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

@@ -3,7 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [API (api2 / TOGa API v2) Architecture](architecture.md) | `api2` is the backend powering the public **TOGa 2.0 API**. | api2/Controller/Index.php, api2/Component/Api/V2/V2.php, api2/Component/Api/Cxml/Cxml.php, api2/Component/Api/V2/Response/Response.php, api2/Config/ |
-| [API Payload Interceptors (metadata-registered prePost/postPut model hooks)](features/api-payload-interceptors.md) | A `_Model`'s `prePost()` / `postPost()` / `prePut()` / `postPut()` hooks are **not** called by the model. | api2/Component/Api/V2/V2.php, api2/Controller/Index.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Elite/SalesOrder.php, dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql |
+| [API Payload Interceptors (metadata-registered prePost/postPut model hooks)](features/api-payload-interceptors.md) | A `_Model`'s `prePost()` / `postPost()` / `prePut()` / `postPut()` hooks are **not** called by the model. | api2/Component/Api/V2/V2.php, api2/Controller/Index.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/SalesOrderItem.php, dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql |
 | [Multi-Client (Cross-Client) Data Retrieval](features/cross-client-data-retrieval.md) | A single authenticated V2 GET listing can return records across **many** clients (designed for 1000+) that the caller is entitled to, honoring **each target cli | api2/Component/Api/CrossClient/CrossClient.php, api2/Component/Api/V2/V2.php, api2/Controller/Index.php, _underscore/Model/Cache/Table.php, _underscore/Model/Cache/Tables/Client.php, _underscore/Model/Core/Record.php, worker2/Worker/Platform/Cache.php, worker2/Controller/Index.php, worker2/_.php, dbchanges2/Cache/2026-06-30a - MultiClientCacheTables.sql, dbchanges2/Core/2026-06-30b - CacheClusterRegistrationAndRecordTtl.sql, dbchanges2/Core/2026-07-27a - PlatformCacheCleanCron.sql |
 | [Encrypted-User-UUID Auth Handoff (/auth/encrypted-user-uuid)](features/encrypted-user-uuid-auth-handoff.md) | `POST /auth/encrypted-user-uuid` is the intended **cross-client / SSO-handoff identity mechanism**: given an encrypted `{client, user}` UUID pair, it mints a fr | api2/Component/Api/CrossClient/CrossClient.php |
 | [ENVIRONMENT (not the EB environment name) decides the _underscore branch and Config file](features/environment-variable-drives-underscore-branch.md) | An api2 Elastic Beanstalk instance decides **which `_underscore` branch it clones** and **which `Config/<env>.ini` it loads** from the EB environment property * | api2/.ebextensions/git.php, api2/.ebextensions/php_include_underscore.config, api2/.ebextensions/git.sandbox-dev.json, api2/Config/beta.ini, api2/Config/sandbox-dev.ini, api2/Component/Api/V2/V2.php |

package/knowledge/2.0/apps/api2/features/api-payload-interceptors.md

@@ -6,13 +6,15 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-10
+updated: 2026-08-11
 owners: ["mhammontree", "dfranks", "bala"]
 files:
   - api2/Component/Api/V2/V2.php
   - api2/Controller/Index.php
   - _underscore/Model/Client/ItemFulfillment.php
   - _underscore/Model/Elite/SalesOrder.php
+  - _underscore/Model/Compass/SalesOrder.php
+  - _underscore/Model/Compass/SalesOrderItem.php
   - dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql
 related:
   - ./record-scripts.md
@@ -22,6 +24,7 @@ related:
   - ../../_underscore/features/config-group-access.md
   - ../../worker2/features/creating-worker-actions.md
   - ../../../clients/elite/features/salesorder-netsuite-push.md
+  - ../../../clients/compass-usa/features/sales-order-line-renumbering.md
 ---
 
 ## Summary
@@ -106,9 +109,56 @@ model does not define takes the endpoint down** with a PHP fatal —
 mirror image of the "missing row" failure mode above: a *missing* row is silent, an *extra/wrong*
 row is fatal.
 
+The post-processing site reads
+`$clientModelName::{$interceptorEntry['phpMethod']}(api: $api, payload: $outData);` — `phpMethod`
+is a key **derived in PHP at lookup time**, not a column, so nothing between the SQL row and the
+call can reject a name the class does not implement.
+
 **Fix direction:** guard all four sites with `method_exists()` and raise a logged `Logs.Issue`
 instead of letting the request fatal.
 
+**Measured blast radius (Compass, 2026-08-05 → 2026-08-06).** A single row wiring `POST`/`POST` on
+`sales-order-items` resolved to `_Model_Compass_Usa_SalesOrderItem::postPost()`, which was never
+written. Result: **270 failed Compass order submissions over ~15 hours** (2026-08-05 17:16 →
+2026-08-06 07:58), every one an opaque `EO-1` 500 with no message. This is the cost of the missing
+guard — not a degraded response, a dead write endpoint for one tenant until someone deleted the row.
+
+## There is NO `Records` route for `api-payload-interceptors` — the rows are UNAUDITED
+
+`ApiPayloadInterceptors` has **no `Core.Records` row**, therefore no `/v2` route, therefore no ACL,
+no `Logs.Api` entry, and **no change history of any kind**. Every add, edit, and delete is direct
+SQL against the client database.
+
+Practical consequences when you are investigating:
+
+- **You cannot answer "who added this row and when."** The 270-order outage above was resolved by
+  deleting a row, and there is no record anywhere of who created it or when — the only evidence is
+  the shape of the 500s in `Logs.Api`.
+- **A fix by row-deletion leaves no trace either.** "It stopped happening" is the whole audit trail.
+  Record the before/after row set in the ticket or in this KB, because the database will not.
+- **Snapshot the table before you change it** (`SELECT` the client's full row set to the ticket).
+  It is a small table and the prod-vs-environment full-table compare is already the standard
+  diagnostic — that same dump is the only rollback you have.
+
+## `postDelete` can NEVER run — delete-time logic must live in `preDelete`
+
+The post-processing interceptor block in `api2/Component/Api/V2/V2.php` (~L5692) executes **only
+when `$outData` is non-null**, and a **successful DELETE always sets `$outData = null`**. So a
+`(recordId, POST, DELETE)` row is dead on arrival: the method is never called, and — exactly like
+the missing-row case — there is no error and no log line to tell you.
+
+**Therefore any logic that must react to a deletion runs in `preDelete`, and must exclude the row
+that is about to disappear**, because at `preDelete` time it is still present. The Compass line
+renumberer takes the id explicitly for this reason:
+`renumberLineNumbers($salesOrderId, excludeSalesOrderItemId: $id)`. See
+[Compass sales-order line renumbering](../../../clients/compass-usa/features/sales-order-line-renumbering.md)
+for the worked wiring.
+
+Corollary for design: when delete-time work also needs the *parent* to be consistent afterwards,
+prefer hooking the **parent** record's `postPost`/`postPut` — the parent hook fires reliably as the
+request's first-resolved record, whereas the child hook has both the `$outData` constraint above and
+the undefined-method risk.
+
 ### The client-model resolution that decides which class must define the method
 
 At `~L5681-5690` the engine derives the concrete class by `str_replace`-ing `_Model_Client_` →
@@ -223,7 +273,15 @@ and the failing environment**. It is a small table, and the drift is usually exa
 - **⚠ An interceptor row for a method that does not exist is a production outage, not a no-op.**
   The dispatch is unguarded at all four call sites — the endpoint fatals with *"Call to undefined
   method"*. If a write endpoint suddenly 500s for one client only, list that client's
-  `ApiPayloadInterceptors` rows and confirm every derived method exists.
+  `ApiPayloadInterceptors` rows and confirm every derived method exists. Measured cost of one such
+  row: **270 failed Compass order submissions in ~15 hours.**
+- **⚠ A `(POST, DELETE)` row is silently dead** — the post block runs only when `$outData` is
+  non-null and a successful DELETE nulls it. Use `preDelete` (excluding the row being deleted), or
+  hook the parent record instead.
+- **⚠ These rows have no route, no ACL and no audit trail.** `api-payload-interceptors` has no
+  `Core.Records` row, so every change is direct SQL and nothing records who made it. Snapshot the
+  client's row set into the ticket before and after any change — that dump is your only rollback
+  and your only history.
 - **⚠ A migration that enables an interceptor must insert `isActive = 0`.** Activation is a *data*
   change that switches on a *code* path; if the PHP defining the method is not confirmed deployed to
   that environment, the row takes the endpoint down. Insert inactive, verify the deploy, then flip
@@ -252,6 +310,19 @@ and the failing environment**. It is a small table, and the drift is usually exa
 
 ## Change history
 
+- 2026-08-11 — Three findings from the post-mortem of the `_Model_Compass_Usa_SalesOrderItem::postPost()`
+  outage (investigation only, no code change). (1) **`postDelete` can never fire** — the
+  post-processing block at `V2.php` ~L5692 runs only when `$outData` is non-null and a successful
+  DELETE always sets it to null, so a `(recordId, POST, DELETE)` row is silently dead; delete-time
+  logic must run in `preDelete` and **exclude the row about to be deleted**, or hook the parent
+  record, which fires reliably as the request's first-resolved record. (2) **These rows are
+  completely unaudited** — `api-payload-interceptors` has no `Core.Records` row, hence no route, no
+  ACL, no `Logs.Api` entry and no history; adds and removes leave no evidence, so snapshot the
+  client's row set into the ticket before/after. (3) Quantified the unguarded-dispatch failure:
+  **270 failed Compass order submissions between 2026-08-05 17:16 and 2026-08-06 07:58**, all opaque
+  `EO-1` 500s, ended by deleting one row. Also recorded that the post call site invokes a
+  runtime-derived `$interceptorEntry['phpMethod']`, so nothing validates the name before the call.
+  (bala)
 - 2026-08-10 — Added **Queueing background work from a post interceptor**, five verified rules from
   the Elite sales-order push: (1) `internalApiRequest` returns records **flat** —
   `$response->salesOrders`, not `$response->data->salesOrders` (the `data` envelope exists only on a

package/knowledge/2.0/apps/api2/features/request-logging.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-10
-owners: ["mhammontree", "dfranks"]
+updated: 2026-08-11
+owners: ["mhammontree", "dfranks", "bala"]
 files:
   - api2/Component/Api/V2/V2.php
   - api2/Controller/Index.php
@@ -85,6 +85,27 @@ Practical consequences:
 - **Orphan sweeps only find PARTIAL casualties.** An attempt that rolled back completely leaves no
   row in any table and, with no API log row, no trail at all.
 
+## ⚠ apiproxy's 5xx retry distorts BOTH logs — always read a 500 through `transactionId`
+
+apiproxy retries a 5xx **across regions**, so **one user action produces up to six near-identical
+500 rows** in core `Logs.Api`: same route, same payload, **one shared `transactionId`**, ~2 s apart,
+alternating `instanceId`s. Two consequences, and both have already caused wrong conclusions:
+
+1. **Occurrence counts overstate user impact.** A "burst" is usually one person clicking once.
+   Collapse on `transactionId` before you report how many users were affected — the same applies to
+   `Logs.Issue.totalOccurrences` and to the 1.0 alert's repeat count
+   ([HTTP 500 monitor](../../../1.0/apps/library/features/http-500-error-monitor.md)).
+2. **A retry that succeeds hides the failure from the client log.** The failed attempts land only
+   in **core `Logs.Api`** (failed writes are core-logged — see above), while the retry that
+   returned 200 is written to **`Logs_<Client>.Api`**. So the client log shows a **clean 200 for a
+   request that 500'd first**, and a client-log-only audit reads a partially-failing endpoint as
+   healthy.
+
+**`Logs_<Client>.Api.transactionId` is UNIQUE**, so there is at most **one** client-log row per
+transaction no matter how many times apiproxy retried. That is why the retry attempts cannot appear
+there even in principle — the two logs are not two views of the same rows. Join the two by
+`transactionId` when you need the full attempt sequence for one user action.
+
 ## Blind spots when auditing a client's API traffic
 
 Looking only at `Logs_<Client>.Api` misses four sources:
@@ -156,6 +177,15 @@ re-send.
 
 ## Change history
 
+- 2026-08-11 — Documented how **apiproxy's cross-region 5xx retry distorts both logs**, found while
+  reading prod 500s for Compass: one user action writes up to **six** near-identical core `Logs.Api`
+  500 rows sharing a single `transactionId` (~2 s apart, alternating `instanceId`), so occurrence
+  counts overstate impact; and when a retry **succeeds**, the 200 is written to `Logs_<Client>.Api`
+  while the failed attempts exist **only** in core `Logs.Api` — so the client log can show a clean
+  200 for a request that 500'd first, and a client-log-only audit reads a partially-failing endpoint
+  as healthy. Recorded that **`Logs_<Client>.Api.transactionId` is UNIQUE** (at most one client-log
+  row per transaction), which is why the retry attempts cannot appear there, and that
+  `transactionId` is the join key for reconstructing one user action. No code change. (bala)
 - 2026-08-10 — Added **Querying prod `Logs.Api` without timing out**: any `LIKE` over the
   `mediumtext` `requestPayload`/`responsePayload` times out the `toga_query` MCP call at 300 s even
   for one day. Narrow first on indexed/non-text columns (`dtStamp` + `route` + `responseCode`, or a

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

@@ -49,6 +49,35 @@ controller.
   **`EV-13`** (HTTP 400).
 - **Sort:** `-field` = DESC, bare `field` = ASC. **Do not send `+`** for ascending.
 
+### ⚠ `depth` is not free — the default 3 re-reads child rows and races concurrent deletes
+
+**`depth` defaults to 3 on every request, writes included.** Serialization (`getFullModelData()` in
+`api2/Component/Api/V2/V2.php`) walks the relationship graph to that depth and **re-loads each child
+by primary key** through `_Model::initialize()` (`_underscore/Model.php` ~L705). `_Model`'s build
+**throws when the row is gone**:
+
+```
+Error during Model build for primary key id 'NNNNNN' for '_Model_<Client>_SalesOrderItem'.
+Exactly 1 row was expected to be returned but 0 were.
+```
+
+Nothing catches it, so it surfaces as an **opaque `EO-1` HTTP 500** on a request that did nothing
+wrong. (This is a *different* path from the dangling-FK tolerance in
+[cross-client data retrieval](cross-client-data-retrieval.md), which nulls a failed **FK expansion**
+— the child-collection re-load is not covered by it.)
+
+**The rule for callers:** if another request may be deleting rows in a collection concurrently, a
+response that walks that collection can 500. Two defences, both cheap:
+
+- **Send an explicit `depth` — do not inherit the default.** A write that only needs its own row
+  should send `depth: 1`; that alone stops the serializer from touching the child collection.
+- **Serialize the writes.** Do not run a request that deletes children in parallel with one whose
+  response walks those children. Worked example (a real production 500 burst):
+  [TOGa Commerce order-submit sync sequencing](../../toga2-commerce/features/order-submit-sync-sequencing.md).
+
+The fragility itself is **unfixed** — any depth ≥ 2 response is exposed. Lowering depth removes
+*your* exposure, not the defect.
+
 ### CRITICAL — an unrecognized param silently flips LIST → READ
 
 Any query param the engine does not recognize switches the request onto a **different code
@@ -129,6 +158,15 @@ where=(field:op:value,LOGIC,field:op:value,(nested,OR,nested))
   invisible; re-request with `fields=` to force `EZ-2` and see the denied list.
 
 ## Change history
+- 2026-08-11 — Recorded that **`depth` (default 3) makes a response race concurrent deletes**:
+  `getFullModelData()` re-loads each child by primary key via `_Model::initialize()`, whose build
+  **throws** when the row is gone (*"Exactly 1 row was expected to be returned but 0 were"*),
+  uncaught → opaque `EO-1` 500. Confirmed in production from a `PUT` at default depth walking
+  `salesOrder → salesOrderItems` while a concurrent `DELETE /v2/sales-order-items/*` burst removed
+  those exact rows. Defences for callers: send an explicit `depth: 1` on writes that need only their
+  own row, and never run a child-deleting request in parallel with one whose response walks that
+  collection. Noted this is a **different** path from the dangling-FK tolerance (which nulls a failed
+  FK expansion) and that the underlying fragility is unfixed for any depth ≥ 2. (bala)
 - 2026-08-10 — Recorded that **`fields=` narrows the response but not the SQL SELECT**: `_Model`
   selects every property declared on the class **and its traits**, so a declared-but-missing column
   500s (`EO-1`, MySQL 1054) any request touching that record — including one that named only an

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

@@ -10,5 +10,6 @@
 | [Config-Driven Expedited Shipping Gating (Cart)](features/expedited-shipping-gating.md) | On the toga2-commerce **Cart** page, expedited shipping options (**"2nd Day EOB"** and **"Next Day Air"**) are only offered in the *Shipping Method* dropdown wh | toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/CartPage.tsx |
 | [Filter / Search-Results Page & the Two Search Entry Points](features/filter-search-results-page.md) | The storefront has **two distinct search entry points that render the same card component through completely different code paths and different FIELDS files**. | src/pages/Filter/FilterPage.tsx, src/pages/Filter/viewModel/useFilterViewModel.ts, src/pages/Filter/viewModel/FIELDS/COMPASS/ENGLISH/USER/FILTERPAGEFIELDS.json, src/pages/Filter/viewModel/FIELDS/COMPASSCANADA/FRENCH/USER/FILTERPAGEFIELDS.json, src/pages/Filter/viewModel/FIELDS/QUAD/ENGLISH/BUYER/FILTERPAGEFIELDS.json, src/components/Header/Header.tsx, src/pages/Home/view/components/BundlesSection.tsx, src/pages/Home/viewModel/FIELDS/COMPASS/ENGLISH/USER/HOMEPAGEFIELDS.json, src/components/Cards/BundleViewCard.tsx, src/utils/renderBadge.tsx, src/hooks/useAssignClientFields.ts |
 | [Multi-Tenant Resolution & Theming](features/multi-tenant-theming.md) | `toga2-commerce` serves multiple clients from one codebase. | src/themeConfig/themes.json, src/themeConfig/ThemeContext.tsx, src/themeConfig/types.ts, src/components/ThemeSwitcher/ThemeSwitcher.tsx, src/components/AuthLayout/AuthLayout.tsx, src/api/axiosInstance.ts, src/contexts/AuthContext.tsx, tailwind.config.js |
+| [Order-submit sync sequencing (useSubmitOrder) — why these calls must not run in parallel](features/order-submit-sync-sequencing.md) | Submitting an order from the cart fires **two independent sync routines** — one for the sales-order header (`syncSalesOrderData`) and one for the line items (`s | toga2-commerce/src/pages/OrderDetails/hooks/useSubmitOrder.ts, toga2-commerce/src/api/syncSalesOrdersDataFromLocalStorageCartToApi.ts, toga2-commerce/src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts |
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-commerce` (React + Vite, "commerce2-react") builds and deploys on **AWS Amplify**. | toga2-commerce/amplify.yml, toga2-commerce/.gitattributes, toga2-commerce/package.json, toga2-commerce/.github/workflows/sync-stage-environments.yml |
 | [Cart e2e — Cypress conventions & harness (toga2-commerce)](workflows/cypress-testing.md) | The Cypress **e2e** convention set for `toga2-commerce`, and the first **active** e2e coverage for the **Cart** page (`cartV2.cy.ts`, slice 1 — 12 tests, verifi | toga2-commerce/cypress/e2e/cartPage/cartV2.cy.ts, toga2-commerce/cypress/fixtures/cart/fetchSingleUserAdmin.json, toga2-commerce/cypress/fixtures/cart/fetchLocations.json, toga2-commerce/cypress/fixtures/cart/fetchUserShippingMethods.json, toga2-commerce/cypress/support/commands.ts, toga2-commerce/cypress/support/e2e.ts, toga2-commerce/src/pages/Cart/CartPage.tsx, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/view/cartForm/CartFormSection.tsx, toga2-commerce/src/pages/Cart/view/cartTable/CartContentsTable.tsx, toga2-commerce/src/pages/Cart/view/cartTable/CartTableItem.tsx, toga2-commerce/src/components/Inputs/AdvancedInput.tsx, toga2-commerce/src/components/BaseButton/BaseButton.tsx |

package/knowledge/2.0/apps/toga2-commerce/features/order-submit-sync-sequencing.md

@@ -0,0 +1,115 @@
+---
+title: Order-submit sync sequencing (useSubmitOrder) — why these calls must not run in parallel
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-08-11
+owners: ["bala"]
+files:
+  - toga2-commerce/src/pages/OrderDetails/hooks/useSubmitOrder.ts
+  - toga2-commerce/src/api/syncSalesOrdersDataFromLocalStorageCartToApi.ts
+  - toga2-commerce/src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts
+related:
+  - ./cart-bundle-submission-and-identity.md
+  - ../architecture.md
+  - ../../api2/features/v2-rest-query-contract.md
+  - ../../../clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md
+---
+
+## Summary
+
+Submitting an order from the cart fires **two independent sync routines** — one for the sales-order
+header (`syncSalesOrderData`) and one for the line items (`syncSalesOrderLocalStorage`). Running them
+**concurrently is not safe**: the header sync's responses are serialized by api2 at the **default
+depth 3**, which walks down into `salesOrderItems` and re-reads each line by primary key, while the
+item sync is deleting those exact lines. The loser of that race is an **uncaught api2 500**.
+
+**The rule: the item sync must complete before the header sync starts.** Anything on this path that
+does not need child data must also send an explicit `depth: 1`.
+
+## How it works
+
+`useSubmitOrder` drives the submit. The two routines are:
+
+| Routine | File | What it does |
+|---|---|---|
+| `syncSalesOrderData()` | `src/api/syncSalesOrdersDataFromLocalStorageCartToApi.ts` | header-level writes, including `updateSalesOrderEmails()` |
+| `syncSalesOrderLocalStorage()` | `src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts` | reconciles the cart's lines against the order — **issues `DELETE /v2/sales-order-items/{uuid}` for removed lines** |
+
+`updateSalesOrderEmails()` runs **first** inside `syncSalesOrderData()`, so it is the earliest
+header request on the wire and the one that collides with the delete burst.
+
+## ⚠ The race — concurrent deletes vs. a depth-3 response
+
+On `_production`, `useSubmitOrder` ran:
+
+```ts
+await Promise.all([syncSalesOrderData(), syncSalesOrderLocalStorage()]);
+```
+
+`updateSalesOrderEmails()` issued `PUT /v2/sales-order-email-addresses/{uuid}` at the **default
+depth 3**. api2 serializes that response by walking
+`salesOrderEmailAddresses → salesOrder → salesOrderItems` and re-loading each child by primary key,
+while `syncSalesOrderLocalStorage()` was concurrently deleting line items. Result:
+
+```
+Error during Model build for primary key id 'NNNNNN' for '_Model_Compass_Usa_SalesOrderItem'.
+Exactly 1 row was expected to be returned but 0 were.
+```
+
+Uncaught → HTTP 500 → opaque `EO-1` for the user, at the last click of the checkout flow.
+
+**Confirmed, not inferred.** The production log timeline shows a `DELETE /v2/sales-order-items/*`
+burst at 14:53:36–38 straddling the failing `PUT` at 14:53:37, and all six `SalesOrderItem` ids
+named in the exception are absent from the database.
+
+## The fix (TRUE-80551)
+
+Three changes, in `toga2-commerce`:
+
+1. **Drop the `PUT` entirely.** `updateSalesOrderEmails()` was writing `existingEmail.emailAddress`
+   back over itself — a **no-op self-overwrite**. The request that caused the outage had no effect
+   in the first place.
+2. **Add `depth: 1` to the remaining `POST`**, so the response never walks the item collection.
+3. **Serialize the two routines** — `syncSalesOrderLocalStorage()` runs to completion *before*
+   `syncSalesOrderData()`.
+
+> **STATUS (2026-08-11): merged to `origin/_beta`, NOT in `origin/_production`.** The production
+> defect is still live — `Logs.Issue` reference `3T` (id 72) is **OPEN**, urgency HIGH, 6
+> occurrences, last seen 2026-08-05 15:21. This needs a production deploy; do not treat the
+> incident as closed because the branch is merged.
+
+## Gotchas / known issues
+
+- **The underlying api2 fragility is NOT fixed.** `getFullModelData()` re-reads children by primary
+  key with no tolerance for a row that vanished mid-request, so **any** depth ≥ 2 response that
+  walks a child collection can still 500 if something concurrently deletes one of those rows.
+  TRUE-80551 removed the request that was hitting it; it did not remove the hazard. See
+  [V2 REST query contract → `depth` is not free](../../api2/features/v2-rest-query-contract.md).
+- **`depth` defaults to 3 on every call, including writes.** A write helper that omits `depth` is
+  opting into a deep read of the order graph it did not ask for. Send `depth: 1` unless you
+  genuinely consume the children.
+- **`Promise.all` over two order-sync routines is the anti-pattern here**, not a performance win.
+  The two routines touch the same rows; the parallelism buys milliseconds and costs a 500 at
+  checkout.
+- **A self-overwriting write is invisible in review but not on the wire.** The failing `PUT` looked
+  like normal maintenance of the email record; it wrote the value it had just read. Check whether a
+  sync call actually changes anything before assuming it must stay.
+- **The failure is a plain `EO-1` to the user** — the real exception only exists in `Logs.Issue`.
+  Resolve `error.id` (`<Issue.reference>-<Event.eventNumber>`) rather than reading the response.
+
+## Change history
+
+- 2026-08-11 — Created from the production investigation of the checkout 500s: `useSubmitOrder`'s
+  `Promise.all([syncSalesOrderData(), syncSalesOrderLocalStorage()])` raced `updateSalesOrderEmails()`'s
+  default-depth-3 `PUT /v2/sales-order-email-addresses/{uuid}` (which walks
+  `salesOrder → salesOrderItems`) against a concurrent `DELETE /v2/sales-order-items/{uuid}` burst,
+  producing *"Exactly 1 row was expected to be returned but 0 were"* → uncaught → 500. Confirmed by
+  the prod log timeline (deletes 14:53:36–38 around the failing PUT at 14:53:37) and by all six
+  referenced item ids being absent from the database. Fix on branch TRUE-80551 — drop the PUT (it was
+  a no-op self-overwrite), send `depth: 1` on the remaining POST, and serialize the item sync before
+  the header sync — **merged to `_beta` only; `Logs.Issue` `3T` is still OPEN in production**.
+  Recorded the residual `getFullModelData()` fragility that the fix does not remove. (bala)

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)_ — 50 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 51 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 46 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 22 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 8 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
@@ -29,7 +29,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **talos** (TOGa IQ) — 7 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 9 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
-- **toga2-commerce** (TOGa Commerce) — 11 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga2-commerce** (TOGa Commerce) — 12 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 11 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 8 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

@@ -11,6 +11,7 @@
 | [Compass MITS Sales-Order Transmission — Rejection Alerting (Issue/Event, not email-in-cron)](features/mits-sales-order-transmission-alerting.md) | 2.0 | When MITS **rejects** a Compass sales order transmitted by the 1.0 cron `1_transmit_compass_sales_orders_to_mits.php`, the alert is no longer an email built ins | worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, worker2/Worker/Infrastructure/Errors.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/IssueEmailAddress.php, dbchanges2/Logs/2026-08-04a - MITS rejection business recipients.sql |
 | [Compass MR/MA Order Auto-Approval & Status Gate](features/mr-ma-order-approval-and-status.md) | 2.0 | Compass **MR** and **MA** sales orders are system-generated from the MITS / Office Depot EDI pipeline (they do not originate as user-entered SA orders) and must | _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/PurchaseOrder.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |
 | [Persona Model & Levy-Sector Gating (worker2 PEOPLE cron)](features/persona-model-and-levy-gating.md) | 2.0 | Compass USA catalogue visibility is driven by **personas** in `Client_Compass`. | worker2/Worker/Client/Compass/PeopleFile.php |
+| [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 |
 | [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 Office Depot Duplicate PO-Line Cleanup (dual-catalog SKU)](workflows/odp-duplicate-po-line-cleanup.md) | 1.0 | The NetSuite fulfillment-sales-order importer duplicated Office Depot purchase-order lines on Compass USA because it reconciled the fulfillment SO against the e | library/app/api/toga2.php, dbchanges2/Client_Compass/2026-07-22a - CleanupOfficeDepotDuplicatePurchaseOrderItems.sql |

package/knowledge/clients/compass-usa/features/sales-order-line-renumbering.md

@@ -0,0 +1,103 @@
+---
+title: Compass Sales-Order Line-Number Renumbering (and why it hangs off the SO hooks)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-08-11
+owners: ["bala"]
+files:
+  - _underscore/Model/Compass/SalesOrderItem.php
+  - _underscore/Model/Compass/SalesOrder.php
+related:
+  - ../../../2.0/apps/api2/features/api-payload-interceptors.md
+  - ../workflows/order-lifecycle-and-data-integrity.md
+  - ./mits-po-to-so-item-linking.md
+---
+
+## Summary
+
+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 (see
+[MITS PO → SO item linking](./mits-po-to-so-item-linking.md)), so a hole in the sequence is not
+cosmetic. `renumberLineNumbers()` on `_Model_Compass_SalesOrderItem` does the renumbering; **where it
+is hooked is the whole story**, because the obvious wiring is impossible and the second-most obvious
+wiring caused a 270-order production outage.
+
+## How it works
+
+`_Model_Compass_SalesOrderItem::renumberLineNumbers($salesOrderId, excludeSalesOrderItemId: …)`
+rewrites the order's lines to a contiguous 1..N sequence. The `excludeSalesOrderItemId` argument
+exists because on the delete path the row **still exists** when the renumberer runs.
+
+Live production wiring (`ApiPayloadInterceptors`, Compass):
+
+| `Core.Records` | route | phase / method | dispatches to |
+|---|---|---|---|
+| **14** | `sales-orders` | `POST` / `POST` | `_Model_Compass_SalesOrder::postPost()` (~L407) → `renumberLineNumbers()` |
+| **14** | `sales-orders` | `POST` / `PUT` | `_Model_Compass_SalesOrder::postPut()` (~L713) → `renumberLineNumbers()` |
+| **15** | `sales-order-items` | `PRE` / `DELETE` | `_Model_Compass_SalesOrderItem::preDelete()` |
+
+Add/edit renumbering rides the **parent** (`sales-orders`) hooks; delete renumbering rides the
+**child**'s `preDelete`.
+
+## Why delete-time renumbering CANNOT be a `postDelete`
+
+A `postDelete` interceptor can never fire at all. api2's post-processing interceptor block runs
+**only when `$outData` is non-null**, and a successful DELETE always sets `$outData = null` — so a
+`(15, POST, DELETE)` row would be registered, valid-looking, and permanently dead, with no error and
+no log line. This is a framework constraint, not a Compass one; full detail in
+[API payload interceptors](../../../2.0/apps/api2/features/api-payload-interceptors.md).
+
+Hence `preDelete`, and hence the `excludeSalesOrderItemId` argument: at `preDelete` time the row is
+still in the table, so the renumberer must be told to skip it or it will number the row that is
+about to vanish.
+
+## ⚠ The wiring that caused the outage — do not repeat it
+
+An earlier attempt registered **`POST`/`POST` on `sales-order-items` (record 15)**. The engine
+derives the method name by convention (`POST`+`POST` → `postPost`) and resolves the class by
+swapping `_Model_Client_` for the JWT client slug, giving `_Model_Compass_Usa_SalesOrderItem` — a
+class that **never had a `postPost()`**. The dispatch is unguarded, so every matching write hit:
+
+```
+Call to undefined method _Model_Compass_Usa_SalesOrderItem::postPost()
+```
+
+**Impact: 270 failed Compass order submissions, 2026-08-05 17:16 → 2026-08-06 07:58**, each an
+opaque `EO-1` 500 with no message for the user.
+
+**Resolution:** the row was deleted and the renumbering relocated to the `sales-orders` hooks, which
+fire reliably as the request's **first-resolved record**. Verified healthy afterwards — **249
+`DELETE /v2/sales-order-items/*` calls in production since 2026-08-06, all HTTP 200.**
+
+## Gotchas / known issues
+
+- **⚠ Never register an interceptor row before confirming the method exists in the deployed
+  `_underscore`.** The dispatch has no `method_exists()` guard; a wrong row is a tenant-wide write
+  outage, not a no-op.
+- **`(POST, DELETE)` rows are silently dead.** Delete-time logic belongs in `preDelete`.
+- **`preDelete` must exclude the row being deleted** — it is still present when the hook runs.
+- **Prefer the parent record's hook for order-wide invariants.** `sales-orders` `postPost`/`postPut`
+  fires as the request's first-resolved record and covers add/edit in one place; per-item hooks add
+  both the `$outData` constraint and the undefined-method risk for no benefit.
+- **The method may be defined once on the shared `_Model_Compass_*` base** — `Usa` and `Canada`
+  subclasses inherit it. Do not add per-region copies.
+- **These interceptor rows have no route and no audit trail.** They are direct SQL only; nothing
+  records who added or removed one. Snapshot Compass's row set into the ticket before changing it.
+
+## Change history
+
+- 2026-08-11 — Documented the as-built wiring and the reasoning behind it after a production
+  post-mortem (investigation only, no code change): add/edit renumbering hangs off
+  `_Model_Compass_SalesOrder::postPost`/`postPut` (record **14** `sales-orders`), delete-time
+  renumbering off `_Model_Compass_SalesOrderItem::preDelete` (record **15** `sales-order-items`,
+  `PRE`/`DELETE`) with `excludeSalesOrderItemId` because the row still exists at that point.
+  Recorded that a **`postDelete` interceptor can never fire** (the post block runs only when
+  `$outData` is non-null and a successful DELETE nulls it), and that the earlier `POST`/`POST` row on
+  `sales-order-items` resolved to the nonexistent `_Model_Compass_Usa_SalesOrderItem::postPost()` and
+  caused **270 failed Compass order submissions between 2026-08-05 17:16 and 2026-08-06 07:58**; the
+  row was removed and the logic relocated. Verified healthy: 249 `DELETE /v2/sales-order-items/*` in
+  production since 2026-08-06, all HTTP 200. (bala)

package/package.json

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