toga-ai 1.0.623 → 1.0.624

package/knowledge/2.0/apps/_underscore/features/record-change-audit-log.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-13
+updated: 2026-08-20
 owners: [bala]
 files:
   - _underscore/Model/Client/Logs/Record.php
@@ -15,6 +15,9 @@ files:
 related:
   - ../../api2/features/request-logging.md
   - ../../../../clients/compass-usa/features/approval-decision-flow.md
+  - ../../../../clients/compass-usa/features/stranded-approval-reassignment.md
+  - ../../api2/features/api-payload-interceptors.md
+  - ../../worker2/features/creating-worker-actions.md
 ---
 
 ## Summary
@@ -90,6 +93,19 @@ single record: the milestone notes are the chapter headings, the field changes a
   automatically. Real example:
   [Compass PEOPLE-file user lifecycle](../../../../clients/compass-usa/features/people-file-user-lifecycle.md),
   whose deactivation batch is a raw `UPDATE Users SET isActive = 0 WHERE id IN (...)`.
+- **⚠⚠ `_Model_Client_Logs_Record::addNote()` IS A SILENT NO-OP OUTSIDE api2.** `addNote()` only
+  **stages** rows into the class's static `$_notes` array. The **only** thing that ever flushes that
+  array is api2's `Component/Api/V2/V2.php`. Nothing in `_underscore` and nothing in `worker2`
+  flushes it. So **any worker or cron that calls `addNote()` loses the note entirely** — no error, no
+  warning, no row. This is the most dangerous failure mode on this page, because the calling code
+  reads as if it audited itself.
+
+  A worker that needs a note must either drain `_Model_Client_Logs_Record::$_notes` itself and INSERT
+  into `Logs_<Tenant>.Record`, or write the `Record` rows directly. Note that
+  **`Logs_<Tenant>.Record.clientId` is `NOT NULL`**, and a worker generally does not have an `$api`
+  to read the client id from — resolve it from `Core` (`Clients` JOIN `Databases` on `name`). Known
+  ids: `Client_Compass` = **2** (`Logs_Compass`), `Client_CompassCanada` = **43**
+  (`Logs_CompassCanada`). This applies to **every** client, not just Compass.
 - **⚠ `Logs_*` and `Core` are on different database clusters — you cannot join them in one query.**
   `Record.recordId` → `Core.Records` and `RecordField.recordFieldId` → `Core.RecordFields` are
   logical foreign keys across a cluster boundary. Resolve the `Core` ids in a **separate** query and
@@ -104,6 +120,14 @@ single record: the milestone notes are the chapter headings, the field changes a
 
 ## Change history
 
+- 2026-08-20 — Added the **`addNote()` is a silent no-op outside api2** gotcha: `addNote()` only
+  stages into the static `$_notes` array and **only api2's `Component/Api/V2/V2.php` ever flushes
+  it**, so every `addNote()` call from `_underscore` or `worker2` loses its note with no error. A
+  worker must drain `$_notes` itself or write `Record` rows directly, and must resolve the
+  `NOT NULL` `Record.clientId` from `Core` (`Clients` JOIN `Databases` on `name`) because it has no
+  `$api` — `Client_Compass` = 2, `Client_CompassCanada` = 43. Found while building the Compass
+  [stranded approval reassignment](../../../../clients/compass-usa/features/stranded-approval-reassignment.md)
+  engine, but it is framework-wide and client-agnostic. (bala)
 - 2026-08-13 — Documented the `Logs_<Tenant>.Record` / `RecordField` field-change audit trail as its
   own subject: the two row shapes (field-change rows with `RecordField` children vs. milestone rows
   carrying only a `note`), scoping by `Record.recordId` = the **`Core.Records` model id**
@@ -119,3 +143,7 @@ single record: the milestone notes are the chapter headings, the field changes a
   request log, the other half of "what happened to this record".
 - [Compass Approval-Decision Flow](../../../../clients/compass-usa/features/approval-decision-flow.md)
   — the investigation this technique was generalized from.
+- [Stranded Approval Reassignment](../../../../clients/compass-usa/features/stranded-approval-reassignment.md)
+  — the worker that hit the `addNote()` no-op and had to write its own `Record` rows.
+- [API Payload Interceptors](../../api2/features/api-payload-interceptors.md) — why api2 is the only
+  tier that flushes staged notes.

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/Rate/Entitlement.php, _underscore/Model/Compass/PurchaseOrder.php, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Elite/ServiceRequest.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/SalesOrderItem.php, dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql, dbchanges2/Core/2026-08-06a - Service request and sales order payload interceptors.sql, dbchanges2/Client_Compass/2026-08-06 - RemoveBrokenSalesOrderItemPostPostInterceptor.sql, dbchanges2/Client_Compass/2026-08-14a - AddSalesOrderInactiveStandaloneItemPreInterceptors.sql, dbchanges2/Client_CompassCanada/2026-08-14a - AddSalesOrderInactiveStandaloneItemPreInterceptors.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/Rate/Entitlement.php, _underscore/Model/Compass/PurchaseOrder.php, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Elite/ServiceRequest.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/SalesOrderItem.php, _underscore/Model/Compass/ApprovalDecision.php, dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql, dbchanges2/Core/2026-08-06a - Service request and sales order payload interceptors.sql, dbchanges2/Client_Compass/2026-08-06 - RemoveBrokenSalesOrderItemPostPostInterceptor.sql, dbchanges2/Client_Compass/2026-08-14a - AddSalesOrderInactiveStandaloneItemPreInterceptors.sql, dbchanges2/Client_CompassCanada/2026-08-14a - AddSalesOrderInactiveStandaloneItemPreInterceptors.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 |
 | [cXML ShipNotice Gateway (ASN ingestion, carrier resolution, per-client provisioning)](features/cxml-shipnotice-gateway.md) | `_Component_Api_Cxml` accepts a supplier `ShipNoticeRequest` and translates it into a `POST /v2/advance-shipping-notices` on the V2 JSON engine. | api2/Component/Api/Cxml/Cxml.php, api2/Component/Api/V2/V2.php, api2/Controller/Index.php |
 | [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 |

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

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-18
+updated: 2026-08-20
 owners: ["mhammontree", "dfranks", "bala", "snaredla", "jcardinal"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -18,6 +18,7 @@ files:
   - _underscore/Model/Elite/ServiceRequest.php
   - _underscore/Model/Compass/SalesOrder.php
   - _underscore/Model/Compass/SalesOrderItem.php
+  - _underscore/Model/Compass/ApprovalDecision.php
   - dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql
   - dbchanges2/Core/2026-08-06a - Service request and sales order payload interceptors.sql
   - dbchanges2/Client_Compass/2026-08-06 - RemoveBrokenSalesOrderItemPostPostInterceptor.sql
@@ -32,6 +33,9 @@ related:
   - ../../_underscore/features/recursive-item-fulfillments.md
   - ../../_underscore/features/config-group-access.md
   - ../../worker2/features/creating-worker-actions.md
+  - ../../../clients/compass-usa/features/stranded-approval-reassignment.md
+  - ../../_underscore/features/record-change-audit-log.md
+  - ../../_underscore/features/email-template-sending.md
   - ../../../clients/elite/features/salesorder-netsuite-push.md
   - ../../../clients/compass-usa/features/sales-order-line-renumbering.md
 ---
@@ -408,6 +412,47 @@ request.** Never conclude "it works on beta" for an in-request read-after-write.
   ambiguous** ("never queued" vs "queued, never consumed"). Both are covered in
   [Creating Worker Actions](../../worker2/features/creating-worker-actions.md).
 
+## Calling a real interceptor FROM a worker — the minimal `$api` shim
+
+The reverse direction of the section above: not "queue a worker from an interceptor" but **"run the
+production interceptor from a worker"**, so a backfill or repair job reuses the business rules
+instead of reimplementing them. This is the right instinct — a duplicated auto-approve threshold or
+email-routing rule will drift from the real one.
+
+**The technique: measure the actual `$api` surface, then fake exactly that.** `$api` looks
+un-fakeable because it is huge, but any single interceptor chain touches very little of it. Trace the
+whole chain reachable from the entry point and you usually find a handful of properties.
+
+Worked measurement (2026-08-20, `_Model_Compass_ApprovalDecision::postPut()`): the **entire** `$api`
+surface reachable from that method is **three properties** — `$api->client`, `$api->httpPayload`,
+`$api->recordUuid`. So a worker can build a 3-property shim and call the genuine `prePut`/`postPut`.
+The Compass repair engine does exactly this; see
+[Stranded Approval Reassignment](../../../clients/compass-usa/features/stranded-approval-reassignment.md).
+
+Rules for doing it safely:
+
+- **Trace the chain, per class — do not generalize the surface from a sibling.**
+  `$api->internalApiRequest` and `$api->route` *do* appear in
+  `_underscore/Model/Compass/SalesOrder.php`, but only inside
+  `_Model_Compass_SalesOrder::postPut()` — a **different class**, not in the `ApprovalDecision`
+  chain. Assuming "the Compass models need `internalApiRequest`" would have produced a shim that was
+  both wrong and larger than needed. Re-measure for every entry point.
+- **A shim is a hard-fail contract.** If the interceptor later starts reading a fourth property, the
+  worker gets a fatal on a `stdClass` with no such property. That is the correct outcome (loud, not
+  silent), but it means the shim must be built where a reviewer will see it, not buried.
+- **Emails still go out.** The interceptors send real mail through the real pipeline, so a worker
+  that runs them is a sending path — cap it, add a `dryRun`, and commit per unit of work, because a
+  sent email cannot be rolled back.
+- **Do not use the interceptor path just to send an email.** For a plain send there is a documented
+  non-API entry point: `_Model_Client_EmailTemplate::send(string $clientIdentifier, ...)`, versus the
+  `$api`-based `sendEmail()`. See
+  [Email Template Sending](../../_underscore/features/email-template-sending.md). Faking `$api` is
+  for reusing *business logic*, not for reaching the mailer.
+- **Notes will not be logged.** `_Model_Client_Logs_Record::addNote()` is flushed only by
+  `Component/Api/V2/V2.php`, so notes staged by the interceptor you just ran are **dropped** in a
+  worker. See
+  [Record Change Audit Log](../../_underscore/features/record-change-audit-log.md).
+
 ## Worked example — the EV-10 that was not a code bug
 
 `_Model_Client_ItemFulfillment::prePost()` defaults `itemFulfillmentStageId` to the shipped stage on
@@ -505,6 +550,17 @@ and the failing environment**. It is a small table, and the drift is usually exa
 
 ## Change history
 
+- 2026-08-20 — Added **"Calling a real interceptor FROM a worker — the minimal `$api` shim"**: the
+  reverse of the queue-from-interceptor path. A worker can reuse production interceptor logic by
+  measuring the `$api` surface an interceptor chain actually touches and faking only that — verified
+  that the **entire** surface reachable from `_Model_Compass_ApprovalDecision::postPut()` is three
+  properties (`client`, `httpPayload`, `recordUuid`). Recorded that the surface must be re-measured
+  **per class** (`$api->internalApiRequest` / `$api->route` appear in
+  `_Model_Compass_SalesOrder::postPut()`, a different class not in that chain), that the shim is a
+  deliberately loud hard-fail contract, that running interceptors really does send email, that
+  `_Model_Client_EmailTemplate::send($clientIdentifier, …)` is the right tool when you only want a
+  mail, and that staged `addNote()` notes are silently dropped outside api2. (bala)
+
 - 2026-08-18 — TRUE-81049: documented that a **POST-processing interceptor cannot persist by
   mutating `$payload`** — `V2.php:5934` passes `$outData`, the outbound response, which the engine
   returns and never saves, so the caller sees the value while the column stays NULL. Added the

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

@@ -5,7 +5,7 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-08-18
+updated: 2026-08-20
 owners: [jcardinal, mhammontree, dfranks, bala]
 files: []
 related:
@@ -461,6 +461,64 @@ $user->username = $username;
 if ($user->load()) { /* found */ }
 ```
 
+### A `LIMIT 1` on a non-unique key MUST have a deterministic `ORDER BY`
+
+* **`LIMIT 1` with no `ORDER BY` does not mean "the first row" — it means an arbitrary row.** MySQL
+  may return whichever row it reaches first, and that choice can change with the query plan, the
+  index chosen, or the physical row order. If the `WHERE` clause is **not** on a unique key, the
+  query is nondeterministic and must carry an `ORDER BY` that breaks every tie.
+* **The same bug hides in `fetchRow()` on an unordered result set** — no `LIMIT 1` to grep for, and
+  it reads as if it were deliberate. When auditing this pattern, search for the single-row
+  *accessors*, not only for `LIMIT 1`.
+* **The tie-break must end in a unique column.** A business-meaning sort such as
+  `ORDER BY isActive DESC` still leaves two active rows tied; append `id` so the ordering is total
+  and the result is reproducible.
+* **Order, do not filter, when "no row" is worse than "a stale row".** `WHERE isActive = 1` makes
+  the lookup return *nothing* for someone who has only an inactive row, which can leave a record
+  with no assignee at all. `ORDER BY isActive DESC, id DESC` preserves the old behaviour in that
+  case while making the active row win whenever one exists. Do not "tighten" such an ordering into
+  a filter.
+* Any column you might assume is unique but is not — `email`, `contactId`, an external personnel
+  number — is in scope. Assume duplicates exist unless a `UNIQUE` constraint says otherwise; verify
+  against prod rather than trusting the column's intent.
+
+```php
+// Bad — arbitrary row when more than one user shares the contact
+$sql = "
+	SELECT
+		Users.id
+	FROM Users
+	WHERE
+		Users.contactId = " . ((int) $contactId) . "
+	LIMIT 1
+";
+
+// Bad — the same nondeterminism, with no LIMIT 1 to notice
+$user = $query->fetchRow();
+
+// Good — active row wins, id makes the ordering total
+$sql = "
+	SELECT
+		Users.id
+	FROM Users
+	WHERE
+		Users.contactId = " . ((int) $contactId) . "
+	ORDER BY
+		Users.isActive DESC,
+		Users.id DESC
+	LIMIT 1
+";
+```
+
+Why this rule exists: duplicate `Users` rows are normal in tenants fed by an HR import, and an
+unordered `LIMIT 1` reliably picked the **older, deactivated** row. Compass order SA135481 sat
+unapproved for 6 days because the approval was stamped with a dead user id. Prod on 2026-08-20 had
+4,510 emails and 368 `contactId`s shared across more than one `Users` row. Note that ordering is
+**prevention only** — it stops a bad id being written, and cannot repair rows already written.
+
+See: clients/compass-usa/features/approval-decision-flow.md and
+clients/compass-usa/features/stranded-approval-reassignment.md
+
 ## PHP
 
 ### PHP Tags
@@ -879,6 +937,14 @@ See: 2.0/apps/worker2/features/cross-account-aws-access.md
 
 ## Change history
 
+- 2026-08-20 — Added "A `LIMIT 1` on a non-unique key MUST have a deterministic `ORDER BY`": an
+  unordered `LIMIT 1` (and `fetchRow()` on an unordered result, which has no `LIMIT 1` to grep for)
+  returns an arbitrary row, so any lookup on a non-unique key needs a tie-break ending in a unique
+  column. Also recorded the rule that you **order rather than filter** when "no row" is a worse
+  outcome than "a stale row" (`ORDER BY isActive DESC, id DESC`, not `WHERE isActive = 1`), and
+  that `email`/`contactId`/personnel numbers are duplicated in practice — prod 2026-08-20 had 4,510
+  emails and 368 `contactId`s shared across multiple `Users` rows. Drawn from Compass order
+  SA135481, unapproved for 6 days because its approval was stamped with a dead user id. (bala)
 - 2026-08-18 - Added "Overrides: match the parent signature exactly": adding a parameter type to an
   override whose parent leaves it untyped is a **fatal at class load** (parameter types are
   contravariant), and `php -l` does not catch it - the class dies at runtime on first model

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)_ — 60 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 61 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 53 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 25 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 8 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

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

@@ -25,6 +25,8 @@ related:
   - workflows/grand-and-toy-asn-backfill.md
   - ../../2.0/apps/api2/features/cxml-shipnotice-gateway.md
   - ../compass-usa/features/approval-decision-flow.md
+  - ../compass-usa/features/stranded-approval-reassignment.md
+  - ../compass-usa/features/people-file-user-lifecycle.md
   - ../compass-usa/features/isfulfillable-data-quality-and-type-rule.md
   - features/french-order-email-localization.md
   - ../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
@@ -92,6 +94,13 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   `clientIdentifier === 'Compass_Canada'` (email-template UUID + EN/FR localization). Fixes to the
   parent cover Canada automatically — no per-tenant change. See
   [Approval-Decision Flow](../compass-usa/features/approval-decision-flow.md).
+- **Canada shares the duplicate-`Users`-row / stranded-approval defect — confirmed 2026-08-20.**
+  `Client_CompassCanada` held **2** approvals assigned to dead duplicate user rows (vs. 53 in
+  `Client_Compass`). Because the PEOPLE importer class and the approval parent are both shared, the
+  prevention fix and the repair engine both cover Canada with no per-tenant change; Core mapping for
+  the log writes is `Client_CompassCanada` = `clientId 43` = `Logs_CompassCanada`. See
+  [Stranded Approval Reassignment](../compass-usa/features/stranded-approval-reassignment.md) and
+  [PEOPLE-File User Lifecycle](../compass-usa/features/people-file-user-lifecycle.md).
 - Assortment (product-grouping) names are served in fr-CA via the `AssortmentTranslations` sidecar
   (16 rows seeded). French was extracted from the old bilingual `"English/French"` `Assortments.name`
   values, which were then cleaned to English-only. See

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

@@ -16,6 +16,7 @@
 | [Compass PEOPLE-File User Lifecycle (duplicate accounts, reactivation grace window, raw-SQL deactivation)](features/people-file-user-lifecycle.md) | 2.0 | The nightly **PEOPLE** file cron (`_Worker_Client_Compass_PeopleFile`, `worker2/Worker/Client/Compass/PeopleFile.php`) owns the whole `Users` row lifecycle for | worker2/Worker/Client/Compass/PeopleFile.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 |
+| [Stranded Approval Reassignment (repointing approvals off dead duplicate Compass Users rows)](features/stranded-approval-reassignment.md) | 2.0 | A Compass employee who leaves and comes back after more than `CONTACT_UNLINK_GRACE_DAYS` (5) is **inserted as a brand-new `Users` row** by the PEOPLE importer i | _underscore/Model/Compass/ApprovalDecision.php, worker2/Worker/Client/Compass/ApprovalReassignment.php, worker2/Worker/Client/Compass/PeopleFile.php |
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |
 | [Compass 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/approval-decision-flow.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-08-18
+updated: 2026-08-20
 owners: ["apeterson", "dfranks", "bala"]
 files:
   - _underscore/Model/Compass/ApprovalDecision.php
@@ -18,6 +18,7 @@ files:
 related:
   - mr-ma-order-approval-and-status.md
   - people-file-user-lifecycle.md
+  - stranded-approval-reassignment.md
   - ../../compass-canada/profile.md
   - ../../compass-canada/features/french-order-email-localization.md
   - ../../../2.0/apps/_underscore/features/email-template-sending.md
@@ -189,7 +190,8 @@ Both paths ultimately produce a **user id** that is stamped onto
 `ApprovalDecisions.assignedToUserId`, and from that moment the approval is bound to that *row*, not
 to that person's email — which is what makes the two gotchas below matter.
 
-**Email lookups must order active-first.** Both delegate lookups now end:
+**Every user lookup on a non-unique key must order active-first.** As of 2026-08-20 all **9**
+such lookups across the two files end:
 
 ```sql
 ORDER BY
@@ -198,10 +200,26 @@ ORDER BY
 LIMIT 1
 ```
 
-`Users.email` uses a case-insensitive collation, and Compass routinely has more than one `Users` row
-per email address (see
-[PEOPLE-file user lifecycle](people-file-user-lifecycle.md)), so an unordered `LIMIT 1` returned
-whichever row the engine happened to pick — in practice the older, deactivated one.
+- `Model/Compass/SalesOrder.php` — **6**: requester by `contactId`; supervisor / manager-for-new-order
+  by `contactId`; both delegate-manager-by-email lookups; the VIP/manager lookup; the manager
+  notification lookup.
+- `Model/Compass/ApprovalDecision.php` — **3**: the requester lookup in `handleApprovalDecision()`,
+  in `_evaluateManagerVip()`, and in `_swapManagerEmailAddress()`.
+
+**`contactId` is just as exposed as `email` — this is not an email-only problem.** Prod 2026-08-20:
+4,510 emails are shared by more than one `Users` row (3,683 spanning an active and an inactive row)
+**and 368 `contactId`s are shared** (260 spanning active and inactive). `Users.email` also uses a
+case-insensitive collation. So an unordered `LIMIT 1` returned whichever row the engine happened to
+pick — in practice the older, deactivated one (see
+[PEOPLE-file user lifecycle](people-file-user-lifecycle.md)).
+
+**Two of the nine had no `LIMIT 1` at all** — they called `fetchRow()` on a fully unordered result,
+which hides the nondeterminism even better than an unordered `LIMIT 1` does. When auditing this
+pattern, do not grep only for `LIMIT 1`.
+
+This is **prevention only**: it stops a *new* approval being written against a dead id, and cannot
+repair rows already written. The repair engine is
+[Stranded Approval Reassignment](stranded-approval-reassignment.md).
 
 **Why `ORDER BY isActive DESC` and not `WHERE isActive = 1`:** filtering would make the delegate
 resolve to *nothing* when the person has **only** an inactive row, leaving the order with **no**
@@ -263,12 +281,13 @@ requester**. All of these comparisons are case-insensitive (`strcasecmp()`), mat
     link text over a `{userOrderUrl}` href that points at **commerce**.
   - **When sweeping templates, match BOTH quote styles.** Compass id `4` uses single-quoted
     `href='…'` and is missed entirely by a double-quote-only regex.
-- **⚠ Pre-existing SQL escaping gap in this path (separate ticket, not fixed).**
-  `_Model_Compass_SalesOrder` ~L978 interpolates `$salesOrderUuid` straight into SQL —
-  `SalesOrders.uuid = '" . $salesOrderUuid . "'` — while ~L1037 **in the same file** correctly uses
-  `_Database::escape()`. The value is route-derived user input: `postPut` takes it as
-  `end(explode('/', $api->route))`. Fix it with `_Database::escape()` per the 2.0 back-end standard;
-  do not copy the unescaped line as a pattern.
+- **SQL injection on `$salesOrderUuid` — FIXED 2026-08-20.** `_Model_Compass_SalesOrder` ~L978
+  interpolated `$salesOrderUuid` straight into SQL (`SalesOrders.uuid = '" . $salesOrderUuid . "'`)
+  while **every sibling query in the same file** already used `_Database::escape()`. The value is
+  route-derived user input (`postPut` takes it as `end(explode('/', $api->route))`), so this was a
+  real injection point, not a style nit. Now escaped. The lesson worth keeping: when one query in a
+  file escapes a value and another does not, the unescaped one is the bug — never assume the
+  inconsistency is deliberate.
 - **⚠ The approval gate is strict user-id equality, so a stale assignment is unrecoverable by the
   user.** `_Model_Client_ApprovalTemplateStage` decides "may this logged-in user act on this stage?"
   by comparing `ApprovalDecisions.assignedToUserId` against the id resolved from the logged-in user's
@@ -279,7 +298,20 @@ requester**. All of these comparisons are case-insensitive (`strcasecmp()`), mat
   it. **Do not relax the gate to match on email**: this model lives in `Model/Client/` and is shared
   by every client, so widening it widens approvals platform-wide. Fix the *data* (repoint
   `assignedToUserId`), not the gate. Duplicate-row root cause:
-  [PEOPLE-file user lifecycle](people-file-user-lifecycle.md).
+  [PEOPLE-file user lifecycle](people-file-user-lifecycle.md); the automated repair is
+  [Stranded Approval Reassignment](stranded-approval-reassignment.md). Real incident: order
+  **SA135481** sat unapproved for 6 days.
+- **⚠ A pure reassignment notifies nobody.** Changing only `ApprovalDecisions.assignedToUserId`
+  sends **no email**: `handleApprovalDecision()` returns early when `isApproved` is absent from the
+  payload, and `handleAssignmentNotification()` fires only for **step 1**. The manager
+  approval-request email is triggered when the **admin approves step 1**, not when an assignment
+  changes. So any tool, backfill, or admin action that repoints a manager must send its own
+  notification if the new approver is meant to hear about it.
+- **`_evaluateManagerVip()` silently no-ops when the order has no requester `Users` row.** It runs
+  `INNER JOIN Users ON Users.contactId = SalesOrders.contactId`; with nothing linked to the order's
+  contact the query returns zero rows and the method returns without evaluating the VIP rule at all.
+  Pre-existing behaviour — a second, distinct way (alongside the no-supervisor POST-path gap below)
+  for an order to never get VIP auto-approve considered.
 - **Stale supervisor links are the bigger source of stuck approvals — and the supervisor path does no
   `isActive` check.** The supervisor-derived manager resolution performs **no validation that the
   supervisor is still active**. Prod, as of **2026-08-12**: **869 active users have a
@@ -359,6 +391,24 @@ requester**. All of these comparisons are case-insensitive (`strcasecmp()`), mat
   approve as manager on his behalf. (Fixed 2026-07-23.)
 
 ## Change history
+- 2026-08-20 — **Made every non-unique user lookup in the approval path deterministic, and fixed an
+  SQL injection.** Added `ORDER BY Users.isActive DESC, Users.id DESC` before `LIMIT 1` to **9**
+  lookups — 6 in `Model/Compass/SalesOrder.php` (requester by `contactId`, supervisor/
+  manager-for-new-order by `contactId`, both delegate-manager-by-email, VIP/manager, manager
+  notification) and 3 in `Model/Compass/ApprovalDecision.php` (`handleApprovalDecision()`,
+  `_evaluateManagerVip()`, `_swapManagerEmailAddress()`). The 2026-08-13 round had treated this as an
+  email-only problem; **`contactId` is exposed identically** (prod 2026-08-20: 368 shared
+  `contactId`s, 260 of them spanning an active and an inactive row, alongside 4,510 shared emails).
+  **Two of the nine had no `LIMIT 1` at all** and called `fetchRow()` on an unordered result. Also
+  **fixed the previously-recorded SQL injection** at `SalesOrder.php` ~L978, which interpolated the
+  route-derived `$salesOrderUuid` raw while every sibling query in the file already escaped it — now
+  `_Database::escape()`. Newly recorded gotchas: a **pure reassignment sends no email** (early return
+  when `isApproved` is absent; `handleAssignmentNotification()` is step-1 only), and
+  **`_evaluateManagerVip()` no-ops** when no `Users` row links to the order's contact. This change is
+  **prevention only** — it cannot repair already-stranded rows; that is
+  [Stranded Approval Reassignment](stranded-approval-reassignment.md), built the same day. Prod
+  incident: order **SA135481**, unapproved for 6 days. `_underscore` branch `TRUE-80864`
+  (committed). (bala)
 - 2026-08-18 — **Migrated the supply order deep link in approval emails to the new supply route.**
   All 5 of the 2.0 link sites (Compass `SalesOrder.php` ~L1059/~L1185, `ApprovalDecision.php`
   ~L422/~L729, `Quad/SalesOrder.php` ~L71) now build
@@ -438,6 +488,8 @@ requester**. All of these comparisons are case-insensitive (`strcasecmp()`), mat
   not yet merged to `_beta`). (apeterson)
 
 ## Related docs
+- [Stranded Approval Reassignment](stranded-approval-reassignment.md) — the repair half: repointing
+  approvals already stamped with a dead duplicate `Users` id.
 - [Compass MR/MA Order Auto-Approval & Status Gate](mr-ma-order-approval-and-status.md) — the
   auto-approval + `_status` gating half of Compass approvals (on `_Model_Compass_SalesOrder`).
 - [Compass Canada](../../compass-canada/profile.md) — uses this identical flow; the runtime

package/knowledge/clients/compass-usa/features/people-file-user-lifecycle.md

@@ -6,13 +6,14 @@ project: Worker
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-08-13
+updated: 2026-08-20
 owners: [bala]
 files:
   - worker2/Worker/Client/Compass/PeopleFile.php
 related:
   - ./persona-model-and-levy-gating.md
   - ./approval-decision-flow.md
+  - ./stranded-approval-reassignment.md
   - ../profile.md
   - ../../../2.0/apps/_underscore/features/record-change-audit-log.md
 ---
@@ -43,9 +44,9 @@ behind the stuck manager approvals described in
   - the reactivation branch — flips `isActive` back to `1` for a matched inactive user.
   - the inactivation batch — a raw bulk `UPDATE` near the end of the run.
 - The class takes a **`$dbName` parameter and is written to serve more than one tenant**
-  (US = `Client_Compass`, with a CA branch in the same class). **Whether Compass Canada is affected
-  by the duplicate-account behaviour is UNVERIFIED** — confirm on `Client_CompassCanada` before
-  shipping any change here, because a fix lands on both tenants at once.
+  (US = `Client_Compass`, with a CA branch in the same class). **Compass Canada IS affected —
+  confirmed 2026-08-20**: `Client_CompassCanada` carried 2 approvals stranded on dead duplicate rows
+  (vs. 53 in `Client_Compass`). A fix here lands on both tenants at once, which is what you want.
 
 ## How it works
 
@@ -104,35 +105,64 @@ rediscovered, and the deactivation path has no model hooks at all (see below).
   an oversight.
 - **`PeopleFile.php` contains a literal SFTP credential in class constants.** Do not paste class
   constants from this file into tickets, docs, or chat transcripts.
-
-## Planned remediation (decided 2026-08-12 — designed, not yet built)
-
-Scope was deliberately narrowed to **one insert-time hook** in `PeopleFile.php`, placed immediately
-after newly inserted users are re-fetched with their new ids. For each newly created user:
-
-1. Find other `Users` rows for the same person — match on `c_hrEmpPersonnelNbr`, fall back to
-   `email`, excluding the newly created row.
-2. Find those rows' `ApprovalDecisions` where `dtDecision IS NULL` (still pending).
-3. **UPDATE** `assignedToUserId` to the new user id — never insert a replacement decision (the
-   one-decision-per-stage invariant is documented in
-   [Approval-Decision Flow](./approval-decision-flow.md)).
-4. Write a `Logs_Compass` `Record` **note** per affected order, because the importer's raw SQL
-   produces no automatic field logging.
-
-No `SalesOrderEmailAddresses` swap is needed — both rows share the same email address.
-
-**Deferred, not rejected:** assign-time manager validation (which would additionally cover a
-delegate that resolves only to dead rows, a delegate that matches nothing, and stale supervisor
-links); an exception report to surface the existing backlog of stuck approvals; and widening
-`loadLookups()` to stop duplicate creation at source.
-
-**Open product question blocking the deferred work:** when a manager has genuinely left and HR has
-supplied no replacement, what should the order do — block, escalate to the supervisor's supervisor,
-or route to an admin queue? This has not been decided, and the remaining remediation cannot be
-specified until it is.
+- **⚠ `DRY_RUN` does NOT protect the source file — a "safe" dry run still deletes the PEOPLE file.**
+  The SFTP delete at the end of `ProcessPeopleFiles()` is gated on **`TEST_MODE` only**, not on
+  `DRY_RUN`. So running the importer with `DRY_RUN = true` still removes the PEOPLE file from
+  `sftp.goagilant.com` and destroys the input you were trying to inspect. Take your own copy of the
+  file first, or set `TEST_MODE`.
+- **⚠ Read newly inserted user ids with `MAX(id)`, on the transaction connection.** A returning
+  employee usually keeps the **same username** as their dead row, so a plain username lookup after
+  the insert can return the **dead** id — which would silently defeat any repair keyed off "the new
+  user". And the new rows are invisible to any other connection until the tenant transaction commits,
+  so the read has to happen on the transaction connection.
+- **`_Model_Client_Logs_Record::addNote()` is a no-op in this cron.** Staged notes are only flushed
+  by api2, so a worker must write its `Record` rows itself. See
+  [Record Change Audit Log](../../../2.0/apps/_underscore/features/record-change-audit-log.md).
+- **`Client_Compass.Users` is 176,057 rows with no index on `c_hrEmpPersonnelNbr`, `email`, or
+  `isActive`.** Any per-row lookup you add against those columns is a full scan of ~174k rows. An
+  index migration is recommended and **not yet done**.
+
+## Remediation — BUILT 2026-08-20
+
+The insert-time hook designed on 2026-08-12 was built, and it grew into a reusable engine rather
+than inline importer code. Full subject doc:
+**[Stranded Approval Reassignment](./stranded-approval-reassignment.md)**. Summary of what changed
+here in `PeopleFile.php`:
+
+- The importer is now a **thin trigger**. It collects the ids of the users it just created and calls
+  the worker action `Client/Compass/ApprovalReassignment/Reassign` — the matching, safety and
+  reassignment logic live on `_Model_Compass_ApprovalDecision`, not in the importer.
+- The trigger fires **after the tenant transaction commits**, so the interceptors it runs (and the
+  emails they queue) can never belong to a transaction that later rolls back.
+- Matching is one non-blank `c_hrEmpPersonnelNbr`, else one non-blank `email`, and it acts **only
+  when exactly one active user matches**.
+- The historic backlog (53 US / 2 CA as of 2026-08-20) was cleared by **direct `UPDATE` SQL, not by
+  running the job** — the sweep would have emailed managers about orders up to 11 months old. See
+  the reassignment doc before ever pointing the sweep at an aged backlog.
+
+**Still deferred, still not rejected:** assign-time manager validation (a delegate resolving only to
+dead rows, a delegate matching nothing, stale supervisor links); an exception report for the standing
+backlog; and widening `loadLookups()` to stop duplicate creation at source.
+
+**Open product question, still open:** when a manager has genuinely left and HR has supplied no
+replacement, what should the order do — block, escalate to the supervisor's supervisor, or route to
+an admin queue? The engine deliberately **skips** these as ambiguous rather than guessing, so the
+question is now contained rather than blocking.
 
 ## Change history
 
+- 2026-08-20 — **Built the remediation** that this doc had recorded as designed-but-unbuilt: the
+  importer is now a thin trigger that collects newly created user ids and calls the new worker action
+  `Client/Compass/ApprovalReassignment/Reassign` **after the tenant transaction commits**; all the
+  matching and safety logic lives on `_Model_Compass_ApprovalDecision`. Full subject:
+  [Stranded Approval Reassignment](./stranded-approval-reassignment.md). Resolved the standing
+  **UNVERIFIED** question — **Compass Canada IS affected** (2 stranded approvals in
+  `Client_CompassCanada` vs. 53 in `Client_Compass`, measured on prod). New gotchas recorded: the
+  SFTP source-file delete is gated on **`TEST_MODE` only, so a `DRY_RUN = true` run still deletes the
+  PEOPLE file**; newly inserted ids must be read with `MAX(id)` **on the transaction connection**
+  because a returning employee reuses their old username; `addNote()` is a no-op in a worker; and
+  `Users` (176,057 rows) has **no index** on `c_hrEmpPersonnelNbr`, `email`, or `isActive`. Ticket
+  TRUE-80864. (bala)
 - 2026-08-13 — Documented the `Users` lifecycle half of the PEOPLE importer as its own subject.
   Root-caused duplicate Compass user accounts to `loadLookups()`, which only sees active users plus
   those deactivated within `CONTACT_UNLINK_GRACE_DAYS` (5): anyone deactivated longer ago cannot be
@@ -151,5 +181,7 @@ specified until it is.
   half of the same cron.
 - [Compass Approval-Decision Flow](./approval-decision-flow.md) — what a duplicate account breaks
   downstream.
+- [Stranded Approval Reassignment](./stranded-approval-reassignment.md) — the engine that repairs the
+  approvals a duplicate account stranded.
 - [Record Change Audit Log](../../../2.0/apps/_underscore/features/record-change-audit-log.md) — why
   the importer's raw writes leave no audit trail.

package/knowledge/clients/compass-usa/features/stranded-approval-reassignment.md

@@ -0,0 +1,206 @@
+---
+title: Stranded Approval Reassignment (repointing approvals off dead duplicate Compass Users rows)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-08-20
+owners: [bala]
+files:
+  - _underscore/Model/Compass/ApprovalDecision.php
+  - worker2/Worker/Client/Compass/ApprovalReassignment.php
+  - worker2/Worker/Client/Compass/PeopleFile.php
+related:
+  - ./approval-decision-flow.md
+  - ./people-file-user-lifecycle.md
+  - ../profile.md
+  - ../../compass-canada/profile.md
+  - ../../../2.0/apps/api2/features/api-payload-interceptors.md
+  - ../../../2.0/apps/_underscore/features/record-change-audit-log.md
+  - ../../../2.0/apps/worker2/features/creating-worker-actions.md
+---
+
+## Summary
+
+A Compass employee who leaves and comes back after more than `CONTACT_UNLINK_GRACE_DAYS` (5) is
+**inserted as a brand-new `Users` row** by the PEOPLE importer instead of being reactivated (root
+cause in [PEOPLE-file user lifecycle](./people-file-user-lifecycle.md)). Any pending approval that
+was stamped with the old row's id is then invisible to the live account, because the can-approve
+gate in the shared `_Model_Client_ApprovalTemplateStage` is a **strict `assignedToUserId` =
+`Users.id`** match. The person keeps getting chased by email (both rows share the address) about an
+order that is not in their queue.
+
+There are two halves to the answer, and they are **not** interchangeable:
+
+1. **Prevention** — every lookup that resolves a user by a non-unique key must order active-first
+   so a *new* approval can never be written against a dead id. Shipped; see
+   [Approval-Decision Flow](./approval-decision-flow.md).
+2. **Repair** — this doc. An engine on `_Model_Compass_ApprovalDecision` that **repoints already
+   stranded** `ApprovalDecisions.assignedToUserId` onto the live duplicate. Prevention cannot fix
+   rows that were already written.
+
+Real incident that drove it: order **SA135481** sat unapproved for 6 days because its step-2 decision
+was assigned to the dead row.
+
+## Key files / entry points
+
+- **`_underscore/Model/Compass/ApprovalDecision.php`** — the engine. Two public entry points:
+  - `reassignApprovalsStrandedOnDuplicatesOfActiveUsers()` — **scoped** mode, driven by the
+    per-import trigger with the ids of the users the importer just created.
+  - `reassignAllApprovalsStrandedOnInactiveDuplicates()` — **sweep** mode, the whole-tenant backfill.
+- **`worker2/Worker/Client/Compass/ApprovalReassignment.php`** — new dispatchable worker action
+  `Client/Compass/ApprovalReassignment/Reassign`. **Defaults `dryRun = true`** — it does nothing
+  destructive unless a caller explicitly passes `dryRun=false`.
+- **`worker2/Worker/Client/Compass/PeopleFile.php`** — reduced to a thin trigger: it collects the ids
+  of newly created users and calls the action **after the tenant transaction commits**.
+
+Both Compass tenants are covered by the same code, because all the behaviour lives in the shared
+parent `_Model_Compass_ApprovalDecision` and the tenant subclasses are empty (see
+[Approval-Decision Flow](./approval-decision-flow.md)).
+
+## How it works
+
+### The matching rule — one active twin or nothing
+
+For a stranded decision assigned to an inactive user, the engine looks for the same human by:
+
+1. the same **non-blank `c_hrEmpPersonnelNbr`**, else
+2. the same **non-blank `email`**.
+
+It acts **only when exactly one active user matches**. Zero matches or more than one match is
+**skipped as ambiguous** — the row is left alone for a human. This is the same "mechanically fixable
+vs. genuinely departed" split already recorded in
+[Approval-Decision Flow](./approval-decision-flow.md): *same human, new account* is repointable;
+*manager who actually left* is not, and guessing would be worse than stalling.
+
+`Users.email` collates `utf8mb4_unicode_ci`, so plain `=` is already case-insensitive — the email
+arm needs no `LOWER()` and must not have one (see gotchas).
+
+### Safety invariants
+
+These are the load-bearing rules of the engine. Anything that changes it must preserve all four:
+
+- **UPDATE only, never INSERT.** Every approval keeps exactly its two decision rows. The
+  one-decision-per-stage / max-two-per-approval invariant is prod-verified and enforced upstream by
+  `Approvals_UNIQUE2` (one `Approval` per sales order, on `recordId` + `primaryKeyId`).
+- **Never touch a decided row.** A decision with `dtDecision` set is history and is skipped.
+- **Delegate to the real interceptors, do not re-implement.** The engine calls the genuine
+  `prePut` / `postPut` rather than copying the VIP auto-approve rule, so the threshold and the email
+  routing keep living in exactly one place. The mechanics of building the minimal `$api` needed for
+  that are in
+  [API Payload Interceptors](../../../2.0/apps/api2/features/api-payload-interceptors.md).
+- **Commit per decision, not per sweep.** Emails are sent by the interceptors, and an email cannot
+  be rolled back — so a crash halfway through must never leave emails sent for work that was undone.
+
+### Batching
+
+The run caps at **5000 decisions** and returns `hasMoreToProcess`. The sweep is **idempotent**
+(a repointed decision no longer matches the stranded predicate), so a larger backlog is cleared by
+simply re-running rather than by raising the cap.
+
+### The trigger has to read new ids with MAX(id) on the transaction connection
+
+A returning employee usually keeps the **same username** as their dead row. So a plain
+username lookup after the insert can return the **dead** id, and the trigger would "repair" the
+approval onto the row it was already stuck on. `PeopleFile` therefore resolves the new ids with
+`MAX(id)`, and it must do so **on the transaction connection** — the rows are not visible to another
+connection until the tenant transaction commits.
+
+The action itself is invoked **after** that commit, so the interceptors it runs (and the emails they
+queue) can never belong to a transaction that later rolls back.
+
+## Measured state (prod, 2026-08-20 — point-in-time, not standing facts)
+
+- Stranded backlog: **53** in `Client_Compass`, **2** in `Client_CompassCanada`, **0 ambiguous** in
+  either. It grows roughly **2 per week**.
+- Duplicate exposure in `Client_Compass.Users` (176,057 rows, 101,116 inactive): **4,510 emails**
+  shared by more than one row (3,683 of them spanning an active and an inactive row) and **368
+  `contactId`s** shared (260 spanning active and inactive). **`contactId` is exposed to the same bug
+  as `email`** — the earlier fix round had treated this as an email-only problem.
+- Core mapping for the logs writes: `Client_Compass` = `clientId 2` = `Logs_Compass`;
+  `Client_CompassCanada` = `clientId 43` = `Logs_CompassCanada`.
+
+## Deferred — the missing indexes
+
+`Client_Compass.Users` has **no index on `c_hrEmpPersonnelNbr`, `email`, or `isActive`**. `EXPLAIN`
+on the stranded-approval query shows `type=ALL` on `ApprovalDecisions` (79,061 rows) plus a
+hash-joined full scan of `Users` (174,463 rows). An index migration in `dbchanges2` is
+**recommended and NOT done** — tolerable today only because the sweep runs nightly against a
+53-row backlog, not because the query is cheap.
+
+## Gotchas / known issues
+
+- **⚠ The backfill was deliberately done by direct SQL, not by running this job.** Running the sweep
+  with `dryRun=false` over the historic backlog would have emailed managers about orders up to
+  **11 months old** (oldest stranded order 2025-09-10) and performed **2 VIP auto-approvals with no
+  human involved**. The one-off catch-up was done with plain `UPDATE` SQL instead, which sends
+  nothing and writes no audit rows. **The worker job exists for the nightly per-import path and
+  future on-demand use — do not point it at an aged backlog without deciding about the emails
+  first.** Consequence to be aware of: the historic rows repaired by hand carry **no `Record` note**,
+  so the audit trail for them is git plus this doc, not `Logs_Compass`.
+- **A pure reassignment sends NO email.** Changing only `assignedToUserId` notifies nobody:
+  `handleApprovalDecision()` returns early when `isApproved` is absent from the payload, and
+  `handleAssignmentNotification()` only fires for step 1. The manager approval-request email fires
+  when the **admin approves step 1**, not when an assignment changes. Anyone who expects the new
+  approver to be told has to add that explicitly.
+- **`_evaluateManagerVip()` silently no-ops when the order has no requester user.** It joins
+  `INNER JOIN Users ON Users.contactId = SalesOrders.contactId`; with no `Users` row linked to the
+  order's contact the query returns zero rows and the function returns without ever evaluating the
+  VIP rule. Pre-existing behaviour, not introduced here — but it means some orders never get VIP
+  auto-approve considered at all. Same family as the no-supervisor POST-path gap in
+  [Approval-Decision Flow](./approval-decision-flow.md).
+- **Do not wrap `Users.email` in `LOWER()`.** The column collates `utf8mb4_unicode_ci`, so `LOWER()`
+  changes **no results** while making the predicate non-sargable. It is a pure loss.
+- **`_Model_Client_Logs_Record::addNote()` does nothing in a worker.** The engine's log notes had to
+  be written explicitly. See
+  [Record Change Audit Log](../../../2.0/apps/_underscore/features/record-change-audit-log.md).
+- **Prevention and repair must both stay.** Deleting the active-first `ORDER BY` because "the sweep
+  fixes it anyway" would reintroduce a window where a person is chased for days before the next run.
+
+## Verification
+
+Replayed **two real production stranded approvals** on a local schema cloned from `Client_Compass`
+and `Logs_Compass`: person `muehea01`, personnel `1451024`, dead id `79444`, live id `280900`;
+orders **SA135553** (admin had approved) and **SA135628** (admin had rejected). The two route
+differently and that difference is the point — SA135553 reassigned **and emailed**, SA135628
+reassigned and **silent**. 27/27 assertions on the replay, plus a 55-scenario / 147-assertion suite
+over the matching rules, the safety invariants, dry run, scoped vs. sweep mode, the VIP rule, email
+routing, log notes, and a 600-row volume case.
+
+## Change history
+
+- 2026-08-20 — **Built the repair engine for approvals stranded on dead duplicate `Users` rows**
+  (the remediation that had been designed-but-unbuilt in
+  [PEOPLE-file user lifecycle](./people-file-user-lifecycle.md)). Added
+  `reassignApprovalsStrandedOnDuplicatesOfActiveUsers()` (scoped, per-import) and
+  `reassignAllApprovalsStrandedOnInactiveDuplicates()` (sweep) to
+  `_Model_Compass_ApprovalDecision`, plus worker action
+  `Client/Compass/ApprovalReassignment/Reassign` (`dryRun` defaults **true**); `PeopleFile.php`
+  became a thin trigger firing **after** the tenant transaction commits. Matching is one non-blank
+  `c_hrEmpPersonnelNbr` else one non-blank `email`, and **only when exactly one active user
+  matches** — anything else is skipped as ambiguous. Invariants: UPDATE-only (never INSERT), never
+  touch a row with `dtDecision`, delegate to the real `prePut`/`postPut` so the VIP threshold stays
+  in one place, and commit per decision so a crash cannot leave emails sent for rolled-back work;
+  capped at 5000/run with `hasMoreToProcess` and idempotent. Recorded that the trigger must read new
+  ids with `MAX(id)` **on the transaction connection** because a returning employee usually reuses
+  their old username. **DECIDED the historic backfill goes through plain `UPDATE` SQL, not this job**
+  — the sweep would have emailed managers about orders up to 11 months old and auto-approved 2 VIP
+  orders unattended. Also recorded: a pure reassignment sends no email at all;
+  `_evaluateManagerVip()` no-ops when no `Users` row links to the order's contact; the prod
+  backlog/duplicate/collation measurements; and the **missing `Users` indexes (not done)**. Verified
+  by replaying real prod orders SA135553/SA135628 (27/27) plus 55 scenarios / 147 assertions.
+  Ticket TRUE-80864. Engine plus worker action **not yet committed** at capture time (held in
+  `_underscore` `git stash@{0}` plus uncommitted worker2 files). (bala)
+
+## Related docs
+
+- [Compass Approval-Decision Flow](./approval-decision-flow.md) — the prevention half (active-first
+  lookups) and the strict user-id approval gate this works around.
+- [Compass PEOPLE-File User Lifecycle](./people-file-user-lifecycle.md) — why the duplicate `Users`
+  rows exist at all.
+- [API Payload Interceptors](../../../2.0/apps/api2/features/api-payload-interceptors.md) — how to
+  run the real `prePut`/`postPut` from a worker instead of duplicating the logic.
+- [Record Change Audit Log](../../../2.0/apps/_underscore/features/record-change-audit-log.md) — why
+  `addNote()` had to be replaced with an explicit write.

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

@@ -18,7 +18,7 @@ project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-08-17
+updated: 2026-08-20
 owners: [jcardinal, bala, tcox, apeterson, dfranks]
 files: []
 related:
@@ -31,6 +31,7 @@ related:
   - features/cost-centers.md
   - features/isfulfillable-data-quality-and-type-rule.md
   - features/approval-decision-flow.md
+  - features/stranded-approval-reassignment.md
   - workflows/cross-kit-bundle-corruption.md
   - workflows/odp-duplicate-po-line-cleanup.md
   - features/odp-edi-855-acknowledgement-and-overquantity-guard.md

package/package.json

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