toga-ai 1.0.855 → 1.0.856

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

@@ -38,6 +38,7 @@
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | Shared 2.0 `_underscore` NetSuite REST client (`_Component_Api_Netsuite`) — record GET/write, SuiteQL, auth, escaping, logging; open before any 2.0 NetSuite cal |
 | [NetSuite Sales Order sync — ship-to address, phone, and PO reference sourcing](features/netsuite-salesorder-address-phone-sync.md) | Where the shared NetSuite SO importer (`_Trait_Netsuite_SalesOrder`) sources SO#, PO#, and ship-to phone, and the traps in changing it; open before editing this |
 | [Note records have NO author — every `*Notes` model's `contactId` is unwritten](features/note-record-authorship.md) | Every `*Notes` model declares a `contactId` FK but no code writes it — note authorship is unrecoverable from 2.0 data; open before building any note author disp |
+| ["Order For" delegation (Users_DelegatorUsers, the permission gate, originalUserId)](features/order-for-delegation.md) | Server side of "Order For" (TRUE-81848): who may order for whom, where that is enforced, and how the audit column records it. |
 | [Outbound third-party API rate budget (_Component_Api_RateBudget) — designed + staged, NOT merged](features/outbound-api-rate-budget.md) | Design record for a shared outbound API rate budget (one component + one Core table, keyed by `bucketKey`); open when adding call-rate metering/limiting to a 2. |
 | [Legacy page meta (Page::meta) & context-scoped ClientRecordFieldSettings](features/page-meta-context-field-settings.md) | Legacy `Page::meta()` page-meta resolver + context-scoped `ClientRecordFieldSettings`; open when a grid column header is wrong/camelCase, or a `/pages/meta` pag |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | `_underscore` opens three per-client DB connections (data/logs/archive) per request; open when a local or prod request 500s with `Unknown database`, when resolv |

package/knowledge/2.0/apps/_underscore/features/acl-permission-chain.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-18
+updated: 2026-09-21
 owners: ["jcardinal", "mhammontree", "tcox", "bala", "apeterson", "rgirish"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -53,7 +53,11 @@ AclRecordPermissions   →  AclLogicGroups   →  AclLogicGroupExpressions  →
 > rejected with the exact message **`No ACL Logic Groups defined for ACL Record Permissions`**
 > (~L4437 / ~L5845); a missing expression binding fails on the second flag the same way. So an
 > `AclRecordPermissions` row with no `AclLogicGroups` row returns UNAUTHORIZED carrying that string
-> — which means the **chain**, not the grant, is the problem.
+> — which means the **chain**, not the grant, is the problem. The mechanism is
+> `_Model_Core_AclRecordPermission::buildSqlExpression`, which returns **`'(0)'`** when the
+> permission has no logic group — so `allowRead = 1` on its own **denies everything**. Second
+> symptom shape (2026-09-18): a 403 that lists `aclRecordPermissionIds` with the nested child array
+> coming back as `[null, null, null]`.
 
 **Field visibility — `AclFieldPermissions`.** Record-level access alone does **not** expose
 fields. Each field needs a row: `recordFieldId`, `roleId`, `isWritable` (0 = read-only, 1 =
@@ -503,6 +507,15 @@ path on the strength of them.
 > [V2 REST query contract → ACL behavior](../../api2/features/v2-rest-query-contract.md). Confirm
 > the request shape first; it eliminates the entire ACL chain in one step.
 
+**⚠ A `CLIENT` record needs the grant in EVERY `Client_*` DB — a Core row for it is dead metadata.**
+Every ACL lookup in `api2/Component/Api/V2/V2.php` (L3236, L4057, L6502, L7307) switches on the
+record's `aclDatabase` and reads only the matching bucket, so `AclRecordPermissions` /
+`AclRecordExpressions` / `AclFieldPermissions` written into `Core` for a `CLIENT` record are **never
+evaluated**. Found 2026-09-18 on record **362** (`user-delegator-users`): role 3 (API) has a Core
+grant and none in any client DB, so no integration can reach the route. For every other client
+record the role-3 grant is mirrored in **both** places (268 rows in `Core`, 275 in
+`Client_Compass`) — mirror it, or the API role silently has nothing.
+
 **Role ids differ per client DB**, so never hardcode a `roleId` in a `CLIENT` ACL migration —
 resolve it with a subselect, e.g. the Base role:
 
@@ -510,6 +523,21 @@ resolve it with a subselect, e.g. the Base role:
 roleId = (SELECT id FROM Roles WHERE `name` = 'Base')
 ```
 
+### ⚠ On a real top-level route, `sqlExpression = '1'` leaks every tenant row
+
+`'1'` (slug `all`) is right for a record only ever read nested under its parent. If the record also
+has its own route, `'1'` lets any user `GET /v2/<route>` and read everyone else's rows. Scope the
+expression to the caller instead — `AclUser` is joined by `_Model_True::isPermitted` on the
+logged-in user:
+
+```sql
+CASE WHEN Users_DelegatorUsers.userId = AclUser.id THEN 1 ELSE 0 END
+```
+
+Caught in security review on `user-delegator-users` (2026-09-18), where a `'1'` grant would have
+listed who every colleague may order for. See
+[order-for delegation](./order-for-delegation.md).
+
 ## Canonical example (grant the Base role full CRUD on a record)
 
 ```sql
@@ -893,6 +921,14 @@ hardcoded `Core.RecordFields` id literals instead of a subselect.
       and every repo is on the **same branch** so the generated model matches the DB.
 
 ## Change history
+- 2026-09-21 — Named the mechanism behind the half-built chain: `_Model_Core_AclRecordPermission::buildSqlExpression`
+  returns **`'(0)'`** with no logic group, so `allowRead = 1` alone denies everything (second symptom: 403 listing
+  `aclRecordPermissionIds` with `[null, null, null]`). Added that a `CLIENT` record's grant must exist in every
+  `Client_*` DB — the `aclDatabase` switch at `V2.php` L3236/L4057/L6502/L7307 makes a Core row dead metadata;
+  record 362 (`user-delegator-users`) role 3 is Core-only and therefore unreachable, while every other client record
+  mirrors role 3 in both. Also recorded the caller-scoped row expression pattern
+  (`CASE WHEN <Table>.userId = AclUser.id THEN 1 ELSE 0 END`) required when a record is a real top-level route.
+  (bala)
 - 2026-09-18 — **The `2026-09-17a` fleet migration has a gap: it granted only the PO-first bridges
   325/329, leaving the TO-first siblings 326 (`transfer-orders-purchase-orders`) and 330
   (`transfer-order-items-purchase-order-items`) with ZERO `AclRecordPermissions` rows.** Found on

package/knowledge/2.0/apps/_underscore/features/order-for-delegation.md

@@ -0,0 +1,162 @@
+---
+title: "Order For" delegation (Users_DelegatorUsers, the permission gate, originalUserId)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-09-21
+owners: [bala]
+files:
+  - _underscore/Model/Client/Users/DelegatorUser.php
+  - _underscore/Model/Client/User.php
+  - _underscore/Model/Client/Logs/Api.php
+  - api2/Component/Api/V2/V2.php
+  - dbchanges2/Client/2026-09-18a - UsersDelegatorUsersTable.sql
+  - dbchanges2/Core/2026-09-18a - UserDelegatorUserRecords.sql
+related:
+  - ../../api2/features/request-logging.md
+  - ./acl-permission-chain.md
+  - ../../toga2-commerce/features/header-order-for-dropdown.md
+  - ../../toga2-commerce/features/view-as-session-tokens.md
+  - ../../api2/features/encrypted-user-uuid-auth-handoff.md
+---
+
+Server side of "Order For" (TRUE-81848): who may order for whom, where that is enforced, and how the audit column records it. Open before touching `/auth/delegator`, `Users_DelegatorUsers`, or `Logs_<Client>.Api.originalUserId`. Team skill: `/order-for`.
+
+## Summary
+
+A user may place an order **as** another user only when a `Users_DelegatorUsers` row says so.
+Three pieces: the junction table (who may order for whom), the gate
+(`_Model_Client_User::canUserOrderForOtherUser`, checked at both mint points), and the
+`originalUserId` audit column (who actually signed in).
+
+**The table ships EMPTY** — no admin screen, no import. Until rows exist every delegation is
+refused and every delegation dropdown is empty. That is intended, not a bug.
+
+## How it works
+
+### 1. `Users_DelegatorUsers` (every `Client_*` DB)
+
+`id`, `uuid`, `userId`, `delegatorUserId`, UNIQUE on the pair. Read as **"`userId` may order for
+`delegatorUserId`"**. Model `_Model_Client_Users_DelegatorUser`.
+
+Core metadata (`Core/2026-09-18a`): record **362**, route `user-delegator-users`,
+`aclDatabase = CLIENT`, RecordFields **2604** id / **2605** uuid / **2606** userId /
+**2607** delegatorUserId, registered as an **inherent child of record 2 (Users)** so
+`userDelegatorUsers` is readable nested under `/users/{uuid}`.
+
+### 2. The gate — checked TWICE
+
+`_Model_Client_User::canUserOrderForOtherUser($orderingUserId, $orderedForUserId)` (L354), used by
+`getRequestingUser()` / `encryptedUser` (L398) and again by `/auth/delegator` in
+`api2/Component/Api/V2/V2.php`.
+
+- Check 1 = when the encrypted `{client,user}` pair is minted.
+- Check 2 = when `/auth/delegator` exchanges that pair for a token. **This second check is the real
+  control**: the encrypted pair has no expiry and no MAC (`_String::encryptWithKey`, AES-256-CBC
+  keyed on `Core.Parameters.API_SECRET_REFRESH_TOKEN`), so a captured pair could otherwise be
+  replayed forever.
+- `/auth/refresh` re-checks an active delegation, so deleting the row or deactivating either
+  account **ends the live session**, not just new switches.
+
+`V2.php` sets `$isDelegatorAuthRequest = true` as the **first statement** of `case 'delegator'`,
+which then falls through into `case 'encrypted'`; the flag is declared `false` (L609) so a forged or
+expired bearer cannot mint. **Fail-closed is deliberate** — a fail-open default was caught in
+security review before it shipped.
+
+### 3. `originalUserId` audit column
+
+`Logs_<Client>.Api.originalUserId` — nullable int, directly after `userId`
+(`Logs_Client/2026-09-18a`), on `_Model_Client_Logs_Api`. `V2.php` fills it at all three client
+log-write sites plus the CloudWatch entry.
+
+- `userId` = who the token is for · `originalUserId` = who actually signed in · **NULL = no
+  delegation**. No row should ever have `originalUserId = userId`.
+- Verified on local order SA136321: `SalesOrders.createdByUserId` = 124256 (Dawn Anderson), log row
+  `userId 124256 / originalUserId 127046` (Dev Team). Last 200 rows: 126 own-token (NULL) + 70
+  delegated, zero self-referencing.
+
+### 4. ACL — read-only, and scoped to the CALLER
+
+Per-tenant files `Client_Compass/2026-09-18a` and `Client_CompassCanada/2026-09-18a`, `appId 5`
+(TOGa Commerce). **Read only, on purpose:** a role that can write its own row here self-grants the
+right to order for anyone in the tenant.
+
+The row expression is scoped to the caller, never `'1'`:
+
+```sql
+CASE WHEN Users_DelegatorUsers.userId = AclUser.id THEN 1 ELSE 0 END
+```
+
+`user-delegator-users` is a real top-level route, so `'1'` would let any user
+`GET /v2/user-delegator-users` and list who every colleague may order for. `AclUser` is joined by
+`_Model_True::isPermitted` on the logged-in user. Chain rules: [ACL permission chain](./acl-permission-chain.md).
+
+**Role ids differ per tenant** — US Compass **7** = Compass Base, **8** = Manager; Compass Canada
+**8** = Compass Base, **9** = Manager. Canada also needed `Core.RecordScripts` **16**
+(`encryptedUser`) granted to its roles 8 and 9 — it shipped with role 1 only, so every normal Canada
+user got a 403 on a pick. US already had 16 for roles 3/7/8.
+
+**Dev-sandbox needs its own files** (`2026-09-21a … DevSandbox.sql`) because the pinned field ids
+collide there — field ids **2767/2768/2769/2770**, record 362 unchanged. See
+[non-prod metadata drift](../../dbchanges2/workflows/nonprod-metadata-drift-repair.md).
+
+### 5. The front-end call that exists
+
+`toga2-commerce/src/pages/Cart/api/CartApi.ts` → `fetchDelegationList(ownUuid)` returns
+`DelegationOption[]` (`{uuid, name, email}`) — everyone that user may order for, one call, no
+paging. Two hard rules in
+[header order-for dropdown](../../toga2-commerce/features/header-order-for-dropdown.md).
+
+## Gotchas
+
+- **The table is empty in every environment.** "Delegation refused / dropdown empty" is the
+  expected state until someone inserts rows; there is no UI or import to do it.
+- **Never let the `isDelegatorAuthRequest` flag default to true** — the encrypted pair is
+  unauthenticated, replayable input.
+- **Outbound logs never carry `userId` or `originalUserId`.** `_underscore/ApiRequest.php` and
+  `SoapRequest.php` write `direction = OUT` rows for calls TOGa makes to NetSuite/UPS — there is no
+  signed-in user on those. A CodeRabbit review asking for the stamp there was wrong and rejected.
+- **Role 3 (API) cannot reach this record.** Its grant for record 362 was written into `Core`, but
+  `aclDatabase = CLIENT` means Core rows are never consulted — so no integration can read or write
+  `user-delegator-users` through api2 until the grant is mirrored into each `Client_*` DB.
+
+## Still open (next person: do not rediscover)
+
+1. **The front end does not switch the token, so the feature is not real yet.** The header dropdown
+   only saves the pick to localStorage and passes it as a cart form value; it never calls
+   `/auth/delegator` (only admin View As does, in `NavIconList.tsx`). With that, `$api->delegator` is
+   never set, `originalUserId` stays NULL, the gate never fires, and the buyer browses their **own**
+   catalog and prices while "ordering for" someone else. Required switch: `GET
+   /users/encryptedUser?uuid=<target>` → `POST /auth/delegator` → `beginDelegation(tokens,
+   originalUserUuid)` (`src/api/sessionTokens.ts`); `restoreOriginalTokens()` returns with no new
+   login. **One parked-token slot, shared with View As** — the two cannot nest.
+2. **`c_orderSubmittedById` must be stamped server side.** The column exists on `SalesOrders` in
+   `Client_Compass`, `Client_CompassCanada`, `Client_Quad`, with `CustomRecordFields` id 40 on record
+   14 and `_Model_Compass_SalesOrder` L51 as `FIELD_INTEGER`. It is a plain integer, not an FK, so
+   api2 will not resolve a `{uuid}` into it and the client cannot set it. Belongs in
+   `_Model_Compass_SalesOrder::prePost()` (L445; `ApiPayloadInterceptor` 24 is already PRE on POST
+   for record 14), read from `$api->delegator->user`, NULL when there is no delegation — matching
+   1.0 `store/common/compass/convertcarttoorder.php` L28-34. **Reading old data:** of 112,096
+   Compass orders 8,118 have the field set and 7,174 of those equal `createdByUserId`, because the
+   1.0 guard compared a manager id against a contact id.
+3. **`/auth/encrypted` still accepts a delegation pair with no bearer and records no delegator.**
+   Narrowed because Commerce no longer calls it; `toga2-desk` still does for client switching.
+
+## Change history
+
+- 2026-09-21 — Created (TRUE-81848). `Users_DelegatorUsers` + record 362, the two-point
+  `canUserOrderForOtherUser` gate, `Logs_<Client>.Api.originalUserId`, caller-scoped read-only ACL
+  for Compass US/Canada (+ dev-sandbox variants), and `fetchDelegationList`. Table ships empty; the
+  token switch, `c_orderSubmittedById` and the `/auth/encrypted` hole are still open. Team skill
+  `/order-for` (commit d4751825) loads this context. (bala)
+
+## Related
+
+- [request logging](../../api2/features/request-logging.md)
+- [ACL permission chain](./acl-permission-chain.md)
+- [header order-for dropdown](../../toga2-commerce/features/header-order-for-dropdown.md)
+- [view-as session tokens](../../toga2-commerce/features/view-as-session-tokens.md)
+- [encrypted-user auth handoff](../../api2/features/encrypted-user-uuid-auth-handoff.md)

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

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
+updated: 2026-09-21
 owners: ["mhammontree", "dfranks", "bala", "jcardinal"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -21,6 +21,7 @@ related:
   - ./v2-deadlock-retry.md
   - ./environment-variable-drives-underscore-branch.md
   - ../../_underscore/features/error-reporting-issue-event.md
+  - ../../_underscore/features/order-for-delegation.md
   - ../../../../clients/aig/features/entitlement-intake.md
   - ../../../../clients/prudential/features/service-request-auth-rejection-alert.md
   - ../../../../clients/compass-usa/features/mits-po-to-so-item-linking.md
@@ -39,6 +40,7 @@ In `api2/Component/Api/V2/V2.php` (~L2168) every request is logged and routed:
 - **A successful, client-scoped read (GET)** → the **CLIENT log DB** via `_Model_Client_Logs_Api` → table `Logs_<Client>.Api` (e.g. `Logs_Aig.Api`).
 - **A request fails *before* client scoping** (bad/expired auth, unknown client — e.g. `EN-1` / `EN-4`) → the **CORE log DB** via `_Model_Core_Logs_Api` → the core `Logs` DB (older docs call this `Logs_2`). Pre-scope failures land in **Core**, **not** the client log.
 - **A FAILED write attempt (non-2xx on a write) lands in the CORE/writer `Logs`, even when the request authenticated to a client.** The subtle one: the request can carry a valid client JWT (fully scoped to, say, `Aig`) and still have its non-2xx `POST`/`PUT` logged to the production **core `Logs`** on the **writer cluster** (host `api-writer.togahub.com`), **not** to `Logs_<Client>`. So `Logs_<Client>.Api` effectively shows the client's **reads**; **failed writes are in core `Logs`.** (A *successful* write is logged to the client log as normal.)
+- **`Logs_<Client>.Api.originalUserId`** (added 2026-09-18) records **who actually signed in** when the token was minted for someone else: `userId` = the token's user, `originalUserId` = the real person, **NULL = no delegation** (no row should ever have the two equal). `V2.php` fills it at all three client log-write sites plus the CloudWatch entry. **Outbound rows (`direction = OUT`, written by `_underscore/ApiRequest.php` / `SoapRequest.php`) never set either column** — there is no signed-in user on a call TOGa makes out to NetSuite or UPS. See [order-for delegation](../../_underscore/features/order-for-delegation.md).
 - There is also a **config-gated branch** (~L2166): when `_Config::api('log_filepath')` is set, the entry is written to a **file** on the host instead of the DB.
 
 **401 lands in base `Logs`; 403 lands in `Logs_<Client>`.** The pre-scope/post-scope split has a sharp edge on the two auth codes:
@@ -207,6 +209,10 @@ Both a **fallback recovery path** and a **scope diagnostic**. In the TRUE-80179
 - **Query prod `Logs.Api` by narrowing on `dtStamp` (indexed) first**, collect ids, then fetch `mediumtext` payloads by id with `LEFT()`/`SUBSTRING()`. Never start from a `LIKE` over `requestPayload`/`responsePayload`.
 - **Never copy logged rows into committed artifacts** — they carry live Bearer tokens and PII.
 
+## Change history
+
+- 2026-09-21 — Added `Logs_<Client>.Api.originalUserId` (delegation audit: NULL = none, never equal to `userId`) and the rule that outbound `direction = OUT` rows stamp neither user column. (bala)
+
 ## Related
 
 - [api2 architecture](../architecture.md)

package/knowledge/2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-09-17
+updated: 2026-09-21
 owners: [bala, kyalamarthi, apeterson, ajean, jcardinal, rgirish]
 files:
   - dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql
@@ -87,7 +87,16 @@ DELETE FROM AclFieldPermissions WHERE uuid IN ('<literal-1>', …, '<literal-8>'
 
 It can only ever match rows this file inserted. **Reusing the same literal across tenants is valid**
 — `uuid` is unique *per table per database*, and each tenant is a separate database, so one literal
-per (row × file) is enough for the whole fan-out. Keep the `NOT EXISTS` guard on the real unique key
+per (row × file) is enough for the whole fan-out.
+
+**⚠ But do NOT reuse a pinned uuid across two files whose rows have DIFFERENT natural keys**
+(e.g. a prod file and its `…DevSandbox.sql` twin, 2026-09-21). `AclFieldPermissions` rows are
+guarded on `recordFieldId`, which differs per environment, so the `NOT EXISTS` guard lets the
+insert through and the UNIQUE `uuid` key then fails: *"Duplicate entry … for key
+`aclfieldpermissions.uuid`"*. Rule of thumb: **same natural key across environments → keep the same
+uuid** (a row then means the same thing everywhere — `RecordFields` keyed on `recordId+field`,
+record permissions keyed on `recordId+roleId`); **environment-specific natural key → its own
+uuid.** Keep the `NOT EXISTS` guard on the real unique key
 (here `(recordFieldId, roleId)`) so re-running is still a no-op on tenants that already have the
 grant; the literal governs only deletion.
 
@@ -278,6 +287,10 @@ it. Two cheap local checks catch almost everything, and neither needs a sandbox:
 2. **Prove re-runnability by concatenating the file to itself** and running *both copies inside one
    transaction*. If the second pass errors — or changes anything the first pass did not — the file is
    not idempotent, and the executor will eventually run it twice.
+   **First DELETE the rows to reproduce the TARGET environment's starting state**, inside the same
+   transaction, then run the file twice, `SELECT` the resulting counts, and `ROLLBACK`. Rehearsing
+   against your own already-seeded local DB proves nothing — every guard short-circuits. This is
+   what caught the duplicate-uuid failure above, which eyeballing missed.
 
 3. **When the migration must not change behaviour, simulate the OLD rules and the NEW rules inside
    ONE database** and diff the results per population. **Never diff prod against a sandbox clone** —
@@ -353,6 +366,10 @@ concluding a migration is production-safe.
   [FIELD_SQL calculated fields](../../_underscore/features/calculated-sql-fields.md).
 
 ## Change history
+- 2026-09-21 — Narrowed the "reuse one uuid literal across tenants" rule: it holds only when the rows share a
+  natural key. An env-specific twin file (guarded on `recordFieldId`, which differs per environment) reusing the
+  literal dies on `Duplicate entry … aclfieldpermissions.uuid`. Also added the DELETE-first transaction rehearsal
+  (reproduce the target env's starting state, run twice, count, rollback), which is what found it. (bala)
 - 2026-09-17 — Three additions from the Compass persona refactor: a **subtractive** phase cannot
   `NOT EXISTS` against the table it deletes from (**MySQL 1093**) — use a multi-table `DELETE` with a
   self `LEFT JOIN … IS NULL`; comparing a varchar `number` column to a string user-variable can raise

package/knowledge/2.0/apps/dbchanges2/workflows/client-schema-drift-audit.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: workflow
 status: active
-updated: 2026-09-16
+updated: 2026-09-21
 owners: ["bala", "mhammontree", "apeterson", "rgirish"]
 files:
   - dbchanges2/Client_Growrk/2026-05-28.sql
@@ -164,12 +164,19 @@ This is the write-side twin of the read-side rule above (*"the field named in th
 
 ## Gotchas
 
+- **A LOCAL checkout that is many `dbchanges` behind looks exactly like a schema gap — it is not.** Every error in a 2026-09-21 local Compass session was an **existing file never applied** (`Client/2026-09-11a` → `SalesOrderItems.fulfillmentType`, the real cause of an order-submit 400 *"Unknown column 'fulfillmentType'"*; the `Logs_Client` blank-DB `Email`/`EmailAttachment` tables, cause of a 500 *"Table 'logs_compass.email' doesn't exist"*; the `Logs` blank-DB `Issue`/`Event` tables; `Client/2026-08-28b`, `2026-08-28f`, `2026-09-01b`, `2026-09-01c`, `2026-09-14a`, `_modules/netsuite/2026-09-11a`). **Grep `dbchanges2` for the column or table name before writing any SQL.**
+- **Diff a whole environment against prod in ONE pass** — missing tables *and* missing columns together — by comparing `SELECT CONCAT(TABLE_NAME, ':', COUNT(*)) FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = '<db>' GROUP BY TABLE_NAME` on both sides and `comm`-ing the sorted lists. Step 3's per-table diff is for one known traversal path; this is the catch-up sweep.
+
 - **Partial means arbitrary — never assume all-or-nothing.** The observed run landed **6 of 7** columns and **1 of 6** metadata rows from one file. "The migration ran" is not a fact about any individual statement in it.
 - **A `CustomRecordFields` row with no ACL grant is not automatically a defect.** Compare with the healthy client before "fixing" it — `Client_Growrk` recordId 312 (`c_netsuiteInternalSalesOrderId`, `TransferOrders`) has no grant, and `Client_Aig` is identical, so that is the normal cross-client state. Repairing it would be a change, not a fix.
 - **A client can be fine for months and then break on onboarding.** Before a client joins the module, its records resolve to the plain `_Model_Client_*` class with none of the `c_` fields, so the missing columns are unreachable. The 500s begin the day the client is switched onto the module-specific model — which is why the "it has always worked" evidence is misleading. Prove it with `Logs.Api`: successful 200s for the exact same request shape right up to the onboarding timestamp, 500s immediately after.
 - **`ALTER TABLE … ADD COLUMN` was INSTANT here** (MySQL 8.0.39, ~5.4k rows) — a small tenant table needs no maintenance window, but confirm the server version and row count rather than assuming.
 - **Re-running the whole module change-set is the wrong repair** when only one environment drifted: the other statements are already applied and some are not idempotent. Write a scoped catch-up file instead.
 
+## Change history
+
+- 2026-09-21 — Added the local-checkout case (behind on `dbchanges` reads as a schema gap; the fix is always an unapplied existing file — grep first) and the one-pass whole-schema `information_schema` column-count diff. (bala)
+
 ## Related
 
 - [dbchanges2 architecture](../architecture.md)

package/knowledge/2.0/apps/dbchanges2/workflows/nonprod-metadata-drift-repair.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: workflow
 status: active
-updated: 2026-09-16
+updated: 2026-09-21
 owners: ["mhammontree", "bala", "kyalamarthi", "rgirish"]
 files:
   - dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql
@@ -133,6 +133,23 @@ Verified 2026-08-17 on beta `Client_Aig`: **`_modules/netsuite/2026-07-10a - Uni
 
 **5. Related observation, same escalation.** `Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql` and `Client/2026-07-16b - TrackingNumberSignatureTypeFieldPermission.sql` resolve their `recordFieldId` via `SET @fieldId = (SELECT … Core.RecordFields …)` before each INSERT block, with later blocks' `SET`s positioned **after** earlier INSERTs. Two factual consequences observed: (a) reading `Core.RecordFields` from a `Client/` file is itself a **Database-isolation violation** per [architecture.md](../architecture.md); (b) when the file is run in chunks / per client selection, the later block's variables are unset, `WHERE sibling.recordFieldId = NULL` matches nothing, and **0 rows insert with no error** — this silently no-op'd the `measures.measureType` read grant **twice** (first in production, then again in dev-sandbox), each time presenting as "empty unit dropdowns". The architecture-consistent remedy is to **hardcode the `recordFieldId` literal**, which removes the `Core` lookup entirely and with it the half-execution failure mode — but that is exactly the practice blocked by the id-divergence hazard in item 2 above, which is why both go to jcardinal together.
 
+**6. Confirmed again 2026-09-21 — and the failure is WORSE than a duplicate-key error: it truncates
+the file.** `Core/2026-09-18a - UserDelegatorUserRecords.sql` pins `RecordFields` **2604-2607**; on
+dev-sandbox those four ids already belong to record 344 (`ItemCategoryFeatureGroupTranslations`).
+The file dies on its **first** `RecordFields` insert and **every statement after that point never
+runs** — dev-sandbox was left with `Records` 362 present, **zero** `RecordFields`, no
+`InherentRecordChildren` row and no ACL, i.e. a half-registered record that looks provisioned.
+Only the field ids clashed; `Records.id` 362 was free in both.
+
+**Working practice until the escalation is answered:** read `MAX(id)` on the **target** environment
+before pinning, and ship an environment-specific twin file when they differ — here
+`Core/2026-09-21a - UserDelegatorUserRecordsDevSandbox.sql` with ids **2767-2770**, plus matching
+`Client_Compass` / `Client_CompassCanada` ACL twins. Give the twin its **own** uuid literals for any
+row whose natural key is environment-specific (see
+[re-runnable additive migrations](../features/rerunnable-additive-inserts.md)). After running a
+pinned-id `Core/` file anywhere, **verify the tail of the file landed**, not just its first
+statement.
+
 ### Known remaining drift (dev-sandbox, as of 2026-08-03)
 
 - `item-fulfillments.returnAddressId` — the **column exists** but there is **no Core RecordField**. Only needed for the return-label flow.
@@ -154,10 +171,16 @@ All three missing columns are merged in `dbchanges2` `_main`. Note the shape dif
 
 ## Gotchas
 
+- **A pinned-id `Core/` metadata file that hits a duplicate key STOPS THERE** — the record row can exist while its `RecordFields`, `InherentRecordChildren` and ACL silently never ran. Check the last statement's rows, not the first.
+
 - **NO carrier can be tested on ANY non-production environment.** Beta runs `[_underscore] debug_mode = 1`, which routes UPS to `wwwcie.ups.com` (CIE/test), and its `[fedex] oauth` points at `https://apis-sandbox.fedex.com` (production uses `https://apis.fedex.com`). But the carrier **account numbers** in non-prod data are copied from production, and neither test environment accepts a production account — UPS returns **"Missing or invalid shipper number" (120100)** and FedEx returns **HTTP 400**. **Label generation can only be verified in production** until CIE/sandbox-valid test accounts are seeded into non-prod `ShippingCarrierAccountNumbers`. (Remedy = obtain those test accounts; documented as the fix, not done.)
 - **⚠ Beta and production point at the SAME NetSuite account (1095849).** Any beta fulfillment writes to **production** NetSuite. Treat a beta fulfill run as a production side effect.
 - **In dev-sandbox, `Core` and `Client_*` share one cluster**, so a `Core.`-qualified reference in a `Client/` migration resolves there and looks fine. **Production splits them** (prod-core / prod-client) — a clean dev-sandbox run is never proof a migration is cluster-safe (see the architecture doc's hard isolation rule).
 
+## Change history
+
+- 2026-09-21 — Second confirmed case of the pinned `Core.RecordFields` id divergence (2604-2607 belong to record 344 on dev-sandbox) and the worse consequence: the duplicate key **aborts the rest of the file**, leaving a half-registered record. Added the environment-specific twin-file practice (`…DevSandbox.sql`, ids 2767-2770) used for `user-delegator-users`. (bala)
+
 ## Related
 
 - [dbchanges2 architecture](../architecture.md)

package/knowledge/2.0/apps/toga2-commerce/features/header-order-for-dropdown.md

@@ -6,8 +6,8 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-09-17
-owners: [tcox]
+updated: 2026-09-21
+owners: [tcox, bala]
 files:
   - src/components/OrderForDropdown/OrderForDropdown.tsx
   - src/components/OrderForDropdown/useOrderForDropdownViewModel.ts
@@ -18,6 +18,7 @@ files:
   - src/pages/Cart/api/CartApi.ts
   - src/pages/Home/viewModel/FIELDS/COMPASS/ENGLISH/ADMIN/HEADERFIELDS.json
   - src/pages/Cart/viewModel/FIELDS/COMPASS/ENGLISH/ADMIN/CARTPAGE.ts
+  - src/pages/Cart/types.ts
   - cypress/e2e/homePage/orderForDropdown.cy.ts
 related:
   - 2.0/apps/toga2-commerce/architecture.md
@@ -25,6 +26,7 @@ related:
   - 2.0/apps/toga2-commerce/features/cart-notification-emails.md
   - 2.0/apps/toga2-commerce/features/cart-page-config-architecture.md
   - 2.0/apps/toga2-commerce/features/view-as-session-tokens.md
+  - 2.0/apps/_underscore/features/order-for-delegation.md
   - 2.0/apps/toga2-commerce/workflows/cypress-testing.md
 ---
 
@@ -49,11 +51,17 @@ MVVM split: `OrderForDropdown.tsx` (view), `useOrderForDropdownViewModel.ts` (st
 - Menu: search box → yourself first as **"<Name> (Myself)"** → the user list → **Load more** past 100. Check mark on the current pick. `aria` listbox/option roles, Escape closes and returns focus to the trigger, outside click closes.
 - Copy keys under `orderFor`: `isEnabled`, `label`, `searchPlaceholder`, `myselfLabel`, `loadingMessage`, `noOptionsFoundMessage`, `loadMoreLabel` — in all four COMPASS/ENGLISH role files.
 
-### 2. There is no "delegation" API — it is the cart's own user list
+### 2. The delegation list — `fetchDelegationList`, plus the legacy `GET /users` list
 
-Verified 2026-09-17 across `toga2-commerce`, `api2`, `_underscore`, `dbchanges2` and the client-sandbox + prod databases: **no delegation endpoint or table exists.** api2's `/auth/delegator` is the view-as token, unrelated (see [view-as-session-tokens](view-as-session-tokens.md)).
+**Corrected 2026-09-21: a delegation table and API now exist** (TRUE-81848). The 2026-09-17 note here — "no delegation endpoint or table exists" — was true then and is **false now**: `Users_DelegatorUsers` + route `user-delegator-users` ship in every `Client_*` DB, and `/auth/delegator` now enforces the delegation, so it is no longer only the view-as token. Server side: [order-for delegation](../../_underscore/features/order-for-delegation.md).
 
-The list is the same `GET /users` the cart uses, via `getUserOptions()` / `getSearchValuesFromAdvancedInput()` in `src/pages/Cart/api/CartApi.ts`:
+`fetchDelegationList(ownUuid)` in `src/pages/Cart/api/CartApi.ts` returns `DelegationOption[]` (`{uuid, name, email}`, `src/pages/Cart/types.ts`) — everyone that user may order for, one call, no paging. Three rules:
+
+- **Call it BEFORE any token switch.** Once the token belongs to the other person, the signed-in user's own record reads as a **403**.
+- **Never request `id` in the fields** — asking for `id` makes the whole GET 403 for these roles. Use `uuid`.
+- **It returns an empty list today** — `Users_DelegatorUsers` ships empty, with no admin screen and no import.
+
+The list the pill still renders is the same `GET /users` the cart uses, via `getUserOptions()` / `getSearchValuesFromAdvancedInput()` in `src/pages/Cart/api/CartApi.ts`:
 
 - **Admins** get all active users; server-side search when `CARTPAGE settings.isSearchAnyoneEnabled`.
 - **Supervisors** get their direct reports through the `Users@supervisor` join, filtered locally.
@@ -88,6 +96,7 @@ Test ids: `order-for-dropdown`, `order-for-trigger`, `order-for-current-name`, `
 
 ## Gotchas
 
+- **⚠ The pick alone does NOT order for anyone — the front end must switch the token.** Today the pill only stores the pick and passes it as a cart form value; nothing calls `/auth/delegator`. So `$api->delegator` is never set, `originalUserId` stays NULL, the server-side delegation gate never fires, and the buyer browses their **own** catalog and prices while "ordering for" someone else. Required switch: `GET /users/encryptedUser?uuid=<target>` → `POST /auth/delegator` → `beginDelegation(tokens, originalUserUuid)` from `src/api/sessionTokens.ts`; `restoreOriginalTokens()` returns with no new login. **One parked-token slot, shared with View As** — Order For and View As cannot nest. Owned by another developer; not in TRUE-81848.
 - **The `ownerUuid` guard is what makes persistence safe — never drop it.** A persisted pick with no owner check is inherited by the next login or by a view-as target and silently orders for the wrong person. Read the store through `getOrderForUserFor(pick, ownerUuid)`, never raw.
 - **Do not set `useSelectedUserZu` from the header.** The cascade reads the *previous* selected user out of the store (see [cart-notification-emails](cart-notification-emails.md)); writing it early makes the previous-user email cleanup a no-op and strands the old person's notification emails on the order.
 - **A missing `orderFor` key renders nothing, by design.** `useAssignClientFields` has no fallback for a missing key, so Compass Canada and Quad get `undefined` and the component returns `null` — safe default-off. Adding a tenant means adding the key to every role file for that tenant.
@@ -97,6 +106,7 @@ Test ids: `order-for-dropdown`, `order-for-trigger`, `order-for-current-name`, `
 
 ## Change history
 
+- 2026-09-21 — Corrected the "no delegation API exists" finding: `Users_DelegatorUsers`, route `user-delegator-users` and the enforced `/auth/delegator` now exist (TRUE-81848). Added `fetchDelegationList` + `DelegationOption` (call before any token switch; never request `id`), and recorded that without the token switch the pick changes nothing server side. (bala)
 - 2026-09-17 — Pick is now persisted to `localStorage["order-for-zu"]` with an `ownerUuid` guard (TRUE-81852); the submit / edit-order-exit / view-as-return / reload clears were removed, and the cart writes the loaded user back to the store. Spec now 4/4 green. (tcox)
 - 2026-09-17 — Header order-for pill added (TRUE-81851), in-memory hand-off store, cart clears on failed user load. (tcox)
 
@@ -107,4 +117,5 @@ Test ids: `order-for-dropdown`, `order-for-trigger`, `order-for-current-name`, `
 - [cart-notification-emails](cart-notification-emails.md)
 - [cart-page-config-architecture](cart-page-config-architecture.md)
 - [view-as-session-tokens](view-as-session-tokens.md)
+- [order-for delegation (server side)](../../_underscore/features/order-for-delegation.md)
 - [cypress-testing](../workflows/cypress-testing.md)

package/knowledge/2.0/apps/toga2-commerce/features/view-as-session-tokens.md

@@ -6,8 +6,8 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-09-17
-owners: [tcox]
+updated: 2026-09-21
+owners: [tcox, bala]
 files:
   - src/api/sessionTokens.ts
   - src/api/apiBaseUrl.ts
@@ -21,6 +21,7 @@ related:
   - 2.0/apps/toga2-commerce/features/header-order-for-dropdown.md
   - 2.0/apps/toga2-commerce/workflows/cypress-testing.md
   - 2.0/apps/api2/architecture.md
+  - 2.0/apps/_underscore/features/order-for-delegation.md
 ---
 
 How an admin impersonates another user and gets back: the delegated token pair, the parked admin pair in localStorage, and the return path. Open before touching auth tokens, the axios refresh, or the view-as button.
@@ -76,10 +77,12 @@ Seeds a long-lived `ADMIN_ACCESS_JWT`; stubs `/auth/delegator` → `mock-delegat
 ## Open items (out of ticket, not fixed)
 
 - `SENTRY_AUTH_TOKEN` is committed in 25 tracked `.env*` files — treat it as compromised and rotate it. (Never store the value in this KB.)
-- Confirm api2 authorizes `/auth/delegator` **server-side** as admin-only; the client-side gate is not a control.
+- ~~Confirm api2 authorizes `/auth/delegator` **server-side**~~ — **answered 2026-09-21:** it now re-checks `_Model_Client_User::canUserOrderForOtherUser` at mint time (and `/auth/refresh` re-checks it), so a captured encrypted pair cannot be replayed. See [order-for delegation](../../_underscore/features/order-for-delegation.md).
+- **The parked-token slot is shared with "Order For".** There is one `originalAuthTokens` key and `beginDelegation` refuses to overwrite it, so once Order For switches tokens the two features cannot nest — decide the precedence before wiring the Order For switch.
 
 ## Change history
 
+- 2026-09-21 — `/auth/delegator` is now gated server side by the Order For delegation check; noted that Order For will share the single parked-token slot. (bala)
 - 2026-09-17 — Created. Admin pair parked in `originalAuthTokens` on delegation and restored on return; `/auth/encrypted` re-mint removed; single-flight identity-bound refresh (TRUE-81852, commit a8c3a537). (tcox)
 
 ## Related
@@ -88,3 +91,4 @@ Seeds a long-lived `ADMIN_ACCESS_JWT`; stubs `/auth/delegator` → `mock-delegat
 - [header-order-for-dropdown](header-order-for-dropdown.md)
 - [cypress-testing](../workflows/cypress-testing.md)
 - [api2 architecture](../../api2/architecture.md)
+- [order-for delegation](../../_underscore/features/order-for-delegation.md)

package/knowledge/2.0/apps/toga2-commerce/workflows/amplify-build-and-deploy.md

@@ -6,8 +6,8 @@ project: TOGa Commerce
 client: shared
 type: workflow
 status: active
-updated: 2026-09-16
-owners: ["jcardinal", "apeterson", "tcox"]
+updated: 2026-09-21
+owners: ["jcardinal", "apeterson", "tcox", "bala"]
 files:
   - toga2-commerce/amplify.yml
   - toga2-commerce/.gitattributes
@@ -117,6 +117,8 @@ AWS Amplify (build + hosting); GitHub Actions (`sync-stage-environments.yml` + t
   3. Restart the dev server.
 
   A **full `node_modules` wipe is not needed**. Because blox is installed per channel, every branch switch can move the required blox version — treat this class of error as "reinstall blox and clear the Vite cache" before touching any import statement.
+
+  **Second shape of the SAME drift (2026-09-21): the app crashes on any toast.** `package.json` + lock pinned `1.1.1-production.139` while `node_modules` again held `1.0.317`. The **old** blox `Toaster` takes `message` as an **array** and calls `message.map()`; `ToasterList.tsx` passes a string or `{title, content}` matching the **new** one — so `Uncaught TypeError: message.map is not a function` plus a React error boundary on `<Toaster>`, which reads as an app bug. Same fix, plus **restart Vite with `--force`** so it drops the pre-bundled dep cache. Any blox runtime type error is a version check first.
 - **`resolve.dedupe` was missing from commerce's `vite.config.ts`** (a `frontend.md` §11 MUST), which made consuming blox via a local symlink hazardous: `toga-blox-npm/node_modules/` contains its own `react@18.3.1`/`react-dom@18.3.1`, and because blox ships **unbundled**, imports resolve against the nearest `node_modules` — under a symlink that is blox's own, giving a second React copy. This is precisely why supply's symlink workflow works (it has always deduped `react`/`react-dom`/`@tanstack/react-table`) and commerce's did not. Commerce now dedupes `react`, `react-dom`, `react-hook-form`, `react-router-dom`, `framer-motion`, `@tanstack/react-query`, `@tanstack/react-table`.
 - **`package.json` pins blox with a CARET** (`"@agilant/toga-blox": "^1.0.322-sandbox-client.117"`), violating `frontend.md` §13(a) — some published versions ship an empty `dist`, and a caret can float you onto one. Pin exact. Related: the `TRUE-80707` branch pin is **11 versions behind** the `_sandbox-client` branch pin (`1.0.333-sandbox-client.134`); reconcile before merging.
 - **Secret hygiene re-confirmed unremediated 2026-08-26** — the live tokens are still in the tracked `.npmrc` in **both** `toga2-commerce` and `toga25-supply`.
@@ -125,6 +127,10 @@ AWS Amplify (build + hosting); GitHub Actions (`sync-stage-environments.yml` + t
 - **A caret on a PRERELEASE is inert, not floating.** `^1.0.322-sandbox-client.117` resolves to **exactly** `1.0.322-sandbox-client.117`: npm only matches prereleases sharing the same `major.minor.patch`. Verified with `semver.maxSatisfying`. It is still a [frontend standard](../../../standards/frontend.md) §13(a) violation and confusing, but it is **not** a drift risk — don't chase it as one.
 - **Commerce's dependency health is better than supply's**, verified 2026-08-27: all 19 blox peers satisfied (none missing) and `resolve.dedupe` is committed on `TRUE-80707`.
 
+## Change history
+
+- 2026-09-21 — Added the second symptom of stale-`node_modules` blox drift: the old `Toaster` `message.map()` crash on any toast (installed 1.0.317 vs pinned 1.1.1-production.139); fix is installing the locked version and restarting Vite with `--force`. (bala)
+
 ## Related
 
 - [toga2-supply Amplify Build & Deploy](../../toga2-supply/workflows/amplify-build-and-deploy.md) — the base pattern and shared gotchas.

package/knowledge/INDEX.md

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

package/package.json

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