toga-ai 1.0.552 → 1.0.554

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

@@ -47,7 +47,47 @@ controller.
 - **Pagination is `page` + `recordsPerPage`. There is no `limit`/`offset`.** Defaults:
   `recordsPerPage` **25**, `depth` **3**. Max `recordsPerPage` **10000** — exceeding it returns
   **`EV-13`** (HTTP 400).
-- **Sort:** `-field` = DESC, bare `field` = ASC. **Do not send `+`** for ascending.
+- **Sort:** `-field` = DESC, `+field` = ASC, bare `field` = ASC. All three are handled
+  (`V2.php` ~L3673–3682). **Prefer bare for ascending:** the query string is parsed *without*
+  urldecoding (see Encoding rules), so a client that percent-encodes the `+` as `%2B` sends a
+  field literally named `%2Bfield` and the sort is silently dropped. Bare has no such failure mode.
+- **A LIST select is `SELECT SQL_CALC_FOUND_ROWS DISTINCT <table>.<primaryKey>`** (`V2.php:3884`;
+  the aggregate-fields path is the one exception). Two consequences: (a) join fan-out collapses to
+  one row per record, so **duplicate child rows are invisible in the response** — a duplicate join
+  row is not a rendering bug you can see; (b) when the collapsed duplicates carry **different**
+  values in the sorted column, `ORDER BY` has more than one candidate value for a single output row
+  and that record's **position is non-deterministic**. Sorting on a joined column is only stable if
+  the join is genuinely 1:1, or the duplicates agree. Worked example:
+  [category tile sort order](../../toga2-commerce/features/category-tile-sort-order.md).
+
+### ⚠ `depth` 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
 
@@ -129,6 +169,24 @@ 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 — **Corrected the sort contract and documented the `DISTINCT` LIST select.** The old
+  "do not send `+`" was wrong as an absolute: `V2.php` ~L3673–3682 explicitly handles `+` as ASC.
+  The real caveat is encoding — the query string is parsed without urldecoding, so a
+  percent-encoded `+` (`%2B`) becomes part of the field name and the sort is silently dropped;
+  bare remains the recommended ascending form. Also recorded that a LIST select is
+  `SELECT SQL_CALC_FOUND_ROWS DISTINCT <table>.<primaryKey>` (`V2.php:3884`), which hides duplicate
+  join rows entirely **and** makes `ORDER BY` non-deterministic for a record whose collapsed
+  duplicates disagree on the sorted column. Found while diagnosing storefront category tile
+  ordering (duplicate `AssortmentItems` rows for one item). (bala)
+- 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

@@ -6,9 +6,11 @@
 | [Cart Bundle Submission & the bundleUuid Identity Contract](features/cart-bundle-submission-and-identity.md) | How cart **bundles** (kits) are turned into `SalesOrderItems` when a cart is submitted or an existing order is edited, and the **identity-field contract** every | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts, src/utils/formatSalesOrderBundlesFromApi.ts, src/stores/useCartStoreZu.ts, src/pages/OrderDetails/helpers/formatSalesOrderDataFromLocalStorage.ts, src/pages/OrderDetails/view/components/OrderItems.tsx |
 | [Cart Notification Emails — duplicate prevention](features/cart-notification-emails.md) | On the cart "Notifications" section a user can add CC email addresses to an order. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/stores/useEmailOptionsStore.ts, src/stores/useCartSalesQuoteZu.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts |
 | [Cart Page — config-driven form architecture (current state + planned refactor)](features/cart-page-config-architecture.md) | The Cart page (`src/pages/Cart/`) is the most config-heavy page in `toga2-commerce`. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/pages/Cart/view/cartForm/CartFormSection.tsx, src/pages/Cart/view/cartForm/CartFormRenderer.tsx, src/pages/Cart/view/EditCart.tsx, src/pages/Cart/view/EditOrder.tsx, src/pages/Cart/viewModel/useEditOrderOrEditCartViewModel.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts, src/hooks/useAssignClientFields.ts |
+| [Category Tile Order (AssortmentItems.sortOrder) — merchandising a storefront category](features/category-tile-sort-order.md) | **"Move item X to the front of category Y" is a DATA change, not a code change.** The order of item tiles on a storefront category page is driven by exactly one | src/pages/Filter/api/FilterApi.ts, src/pages/Filter/viewModel/useFilterViewModel.ts, api2/Component/Api/V2/V2.php, toga2-supply/src/pages/Items/api/itemsApi.ts |
 | [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Almost no user-facing text, field layout, or page config is hard-coded in `toga2-commerce`. | src/pages/Account/view/MySettingsView.tsx, src/contexts/helpers/getLoginSettings.ts, src/pages/Account/viewModel/useAccountViewModel.ts, src/fieldsConfig/index.ts, src/fieldsConfig/getClientLoginFields.ts, src/fieldsConfig/clientFields/COMPASS.json, src/fieldsConfig/clientFields/COMPASSCANADA.json, src/fieldsConfig/clientFields/QUAD.json, src/pages/Cart/api/CartApi.ts, src/hooks/useAuthenticationFlow.ts, src/contexts/AuthContext.tsx, src/pages/Login/viewModel/useLoginPageViewModel.ts, src/hooks/useAssignClientFields.ts, src/hooks/useDynamicConditionalFieldOptions.ts, src/stores/useFieldsStore.ts, src/components/BaseDetailField/BaseDetailField.tsx, src/components/NavIcons/NavIconItem.tsx, src/components/Submenus/AlertSubmenu.tsx, src/components/Submenus/types.ts, src/pages/Account/AccountPage.tsx, src/pages/Account/view/MyOrdersView.tsx, src/pages/GetSupport/GetSupportPage.tsx, src/pages/GetSupport/viewModel/useGetSupportViewModel.ts, src/queries/queries.ts, src/App.tsx, src/pages/Filter/FilterPage.tsx, src/pages/Filter/viewModel/FIELDS/COMPASS/ENGLISH/USER/FILTERPAGEFIELDS.json |
 | [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/category-tile-sort-order.md

@@ -0,0 +1,164 @@
+---
+title: Category Tile Order (AssortmentItems.sortOrder) — merchandising a storefront category
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-08-11
+owners: [bala]
+files:
+  - src/pages/Filter/api/FilterApi.ts
+  - src/pages/Filter/viewModel/useFilterViewModel.ts
+  - api2/Component/Api/V2/V2.php
+  - toga2-supply/src/pages/Items/api/itemsApi.ts
+related:
+  - filter-search-results-page.md
+  - ../architecture.md
+  - ../../api2/features/v2-rest-query-contract.md
+---
+
+## Summary
+
+**"Move item X to the front of category Y" is a DATA change, not a code change.** The order of
+item tiles on a storefront category page is driven by exactly one column —
+**`Client_<Client>.AssortmentItems.sortOrder`, ascending** — and nothing else. There is no
+merchandising UI, no per-tenant config key, and no client-side re-sort to override.
+
+The trap is that the obvious one-row `UPDATE` **does not work**: in MySQL `ORDER BY … ASC`,
+`NULL` sorts **before** every number, and these columns are normally all `NULL`. Setting only the
+target item to `1` leaves the still-`NULL` siblings ahead of it — the opposite of the request. You
+must give **every active item in that assortment** an explicit `sortOrder`.
+
+## How it works
+
+1. **Category browse** is the `/filter` page with a `category` query param and no `search` text.
+   `useFilterViewModel.ts` runs the `["assortmentItems", categoryUuid, currentPage]` query, which
+   calls `fetchAssortmentItems()` in `src/pages/Filter/api/FilterApi.ts`.
+2. That request joins `Items → AssortmentItems → Assortments` (plus `Personas_Items → Personas`
+   for non-admins), filters to the requested assortment uuid with `Items.isActive = 1` and
+   `Items.catalogId = 1`, pages at `recordsPerPage: 12`, and sorts with exactly:
+
+   ```ts
+   sort: ["AssortmentItems.sortOrder"]
+   ```
+
+3. **api2 treats a bare (unprefixed) sort field as ASC.** (`-` = DESC, `+` = ASC — see
+   [v2-rest-query-contract](../../api2/features/v2-rest-query-contract.md).)
+4. **The frontend never re-sorts.** The view model does a straight
+   `setSortedItems(assortmentItems.data.items)` — despite the `sortedItems` name, no sorting
+   happens there. **The API's row order is the final on-screen order.**
+
+So the only lever is the column. Ties (equal or all-`NULL` values) fall back to whatever MySQL
+returns, which is not a documented or stable order.
+
+## Making the change (the procedure)
+
+Assign an explicit `sortOrder` to **every active item** in the assortment — the two pinned ones,
+then the rest. Pattern (`<assortmentId>` from `Assortments`, item ids from `Items`):
+
+```sql
+# 1. pin the intended leaders
+UPDATE AssortmentItems
+SET sortOrder = 1
+WHERE
+	assortmentId = <assortmentId> AND
+	itemId = <firstItemId>;
+
+UPDATE AssortmentItems
+SET sortOrder = 2
+WHERE
+	assortmentId = <assortmentId> AND
+	itemId = <secondItemId>;
+
+# 2. every remaining ACTIVE item must get a value, or a NULL row jumps to the front
+UPDATE AssortmentItems ai
+	INNER JOIN Items i ON i.id = ai.itemId
+SET ai.sortOrder = 10
+WHERE
+	ai.assortmentId = <assortmentId> AND
+	ai.sortOrder IS NULL AND
+	i.isActive = 1;
+```
+
+Verify with the read the storefront actually performs — ordered, not just spot-checked:
+
+```sql
+SELECT
+	ai.id,
+	ai.itemId,
+	ai.sortOrder,
+	i.itemNumber,
+	i.isActive
+FROM AssortmentItems ai
+	INNER JOIN Items i ON i.id = ai.itemId
+WHERE ai.assortmentId = <assortmentId>
+ORDER BY ai.sortOrder ASC;
+```
+
+**Recommended, not required:** park **inactive** rows at a high value (e.g. `100`) as well. They
+are filtered out today by `Items.isActive = 1`, so they cost nothing now — but if someone
+reactivates one later it comes back with `sortOrder = NULL` and silently takes first position.
+
+## Gotchas
+
+- **`NULL` sorts FIRST in ASC.** The single-row `UPDATE` that "obviously" pins an item produces the
+  opposite result while looking correct in isolation. Always set the whole active set.
+- **Duplicate `AssortmentItems` rows exist and make order non-deterministic.** api2's LIST query
+  selects `SELECT SQL_CALC_FOUND_ROWS DISTINCT <table>.<primaryKey>` (`V2.php:3884`), so two
+  `AssortmentItems` rows for the same `itemId` collapse to **one visible tile** — which is why
+  nobody notices the duplicate. But if the duplicates carry **different** `sortOrder` values, the
+  `ORDER BY` has two candidate values for one output row and the position is unpredictable. When
+  duplicates exist, give them the **same** value or delete the extras. Check first:
+
+  ```sql
+  SELECT itemId, COUNT(*) AS rowCount
+  FROM AssortmentItems
+  WHERE assortmentId = <assortmentId>
+  GROUP BY itemId
+  HAVING rowCount > 1;
+  ```
+
+- **⚠ Editing an item's assortments in TOGa Supply WIPES `sortOrder`.** See Known open items —
+  any ordering you set is one supply edit away from being erased. Re-verify order after anyone
+  edits that item in supply.
+- **A refresh will NOT show the change.** The storefront persists its whole React Query cache to
+  `localStorage["commerce"]` with a 24h `staleTime`, so a warm browser replays the cached
+  response and the (correct) data fix looks like it failed — then gets "re-fixed". The reliable
+  check is **log out and back in** (logout removes the `commerce` key), or
+  `localStorage.removeItem('commerce')`; otherwise it appears within 24h. See
+  [architecture](../architecture.md) gotchas.
+- **This is data, so it does not ride a deploy.** No build, no release notes — which also means no
+  audit trail. Record the assortment id and the values you set in the ticket.
+
+## Known open items
+
+- **⚠ TOGa Supply resets `sortOrder` to `NULL` on any item-assortment edit — unfixed, no ticket
+  filed yet.** In `toga2-supply/src/pages/Items/api/itemsApi.ts`, `updateItemAssortments()`
+  (L645) reads the item's existing rows via `getAssortmentItems()` (L434), which requests only
+  `["assortment.name", "assortment.uuid", "uuid"]` — **never `sortOrder`** — then `DELETE`s every
+  row and `POST`s new ones whose payload carries only `item.uuid` + `assortment.uuid`. The
+  merchandising order is therefore silently destroyed and cannot be restored, because the old
+  values were never read. A fix must select `sortOrder`, and either preserve it on the re-POST or
+  stop the delete-then-recreate in favor of diffing.
+- **Same function: the re-POSTs are never awaited.** `updateItemAssortments()` builds
+  `addPromises` and returns without `await Promise.all(addPromises)` (the `DELETE`s above it *are*
+  awaited). Failures surface as unhandled rejections and the caller cannot know the writes landed.
+  Fire-and-forget `POST`s racing an awaited `DELETE` burst is also the most likely origin of the
+  duplicate rows described in Gotchas. (Related: parallel deletes on a collection can 500 the
+  response of a concurrent read — see
+  [v2-rest-query-contract](../../api2/features/v2-rest-query-contract.md).)
+- **Compass USA "Docking Station" reorder — SQL delivered, NOT executed.** See
+  [Compass USA profile](../../../clients/compass-usa/profile.md).
+
+## Change history
+- 2026-08-11 — Initial doc, from a read-only prod investigation of a Compass USA request to move
+  one item to the front of a category. Recorded that tile order comes solely from
+  `AssortmentItems.sortOrder ASC` (`FilterApi.ts:56`) with no client-side re-sort in
+  `useFilterViewModel.ts`; the **`NULL`-sorts-first** trap that makes a single-row `UPDATE`
+  backfire (the real assortment had `sortOrder = NULL` on all 16 rows); api2's
+  `DISTINCT <primaryKey>` LIST select (`V2.php:3884`) hiding duplicate join rows while making
+  `ORDER BY` non-deterministic when duplicates disagree; and that toga2-supply's
+  `updateItemAssortments()` wipes `sortOrder` (and never awaits its re-POSTs), making any fix
+  non-durable. (bala)

package/knowledge/2.0/apps/toga2-commerce/features/filter-search-results-page.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-07-28
-owners: ["tcox"]
+owners: ["tcox", "bala"]
 files:
   - src/pages/Filter/FilterPage.tsx
   - src/pages/Filter/viewModel/useFilterViewModel.ts
@@ -24,6 +24,7 @@ related:
   - 2.0/apps/toga2-commerce/architecture.md
   - 2.0/apps/toga2-commerce/features/client-fields.md
   - 2.0/apps/toga2-commerce/features/multi-tenant-theming.md
+  - 2.0/apps/toga2-commerce/features/category-tile-sort-order.md
 ---
 
 ## Summary
@@ -53,6 +54,10 @@ bug (see Change history).
 tenant × language × role (see [client-fields](client-fields.md) for the resolver). `FilterPage`
 `renderBundles` maps each result to a `BundleViewCard`.
 
+> **Third mode, same page:** with a `category` param and **no** `search` text, `/filter` is the
+> category *browse* page and runs a different query (`fetchAssortmentItems`) whose row order is
+> data-driven — see [category tile sort order](category-tile-sort-order.md).
+
 ### Home search → in-place filter
 
 The Home page's own lower search bar never leaves `/home`. `BundlesSection.tsx` reads

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) — 13 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/knowledge/clients/compass-usa/profile.md

@@ -17,7 +17,7 @@ project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-08-06
+updated: 2026-08-11
 owners: [jcardinal, bala, tcox, apeterson, dfranks]
 files: []
 related:
@@ -32,6 +32,7 @@ related:
   - workflows/odp-duplicate-po-line-cleanup.md
   - ../../2.0/apps/worker2/features/compass-vip-support-importer.md
   - ../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
+  - ../../2.0/apps/toga2-commerce/features/category-tile-sort-order.md
   - ../../2.0/apps/toga2-commerce/features/cart-bundle-submission-and-identity.md
   - ../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
 ---
@@ -61,6 +62,17 @@ separate, related client (see its own profile).
   **Known data issue:** many Compass MacBooks are categorized `APPLE LAPTOP` /
   `MAC & ACCESSORIES`, not `COMPUTERS`, so those kits do **not** qualify for expedited — a
   catalog-data normalization matter, not a code gap.
+- **Category tile order is data, not code** — `Client_Compass.AssortmentItems.sortOrder ASC` is the
+  only lever; see
+  [Category Tile Order](../../2.0/apps/toga2-commerce/features/category-tile-sort-order.md) for the
+  `NULL`-sorts-first trap and the procedure.
+  **⚠ Pending prod data change (2026-08-11, delivered but NOT executed):** for
+  `Assortments.id = 9` ("Docking Station", all 16 rows had `sortOrder = NULL`), pin
+  `itemId 2712` / `9X3V1UT` → `1` and `itemId 2812` / `AW5M5UT-1` → `2`, and give the remaining
+  active rows an explicit value. Handed off for a DBA / the TOGa UI to run because session DB
+  access was read-only. Also outstanding for that assortment: park the 13 inactive rows at a high
+  `sortOrder`, and remove the duplicate `AssortmentItems` row `id 2982` (duplicate of `2981`, same
+  `itemId 2712`). Confirm whether this was applied before re-diagnosing tile order for Compass.
 - **Cross-kit bundle corruption (edit-order):** a `toga2-commerce` submit bug attributed kit
   line items and shared fees/warranties to the wrong kit; 55 Compass orders / 298 line items are
   corrupted in `Client_Compass.SalesOrderItems` (Canada and Quad: zero). The code fix is

package/package.json

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