toga-ai 1.0.877 → 1.0.879

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: architecture
 status: active
-updated: 2026-09-22
+updated: 2026-09-23
 owners: ["jcardinal", "rgirish", "mhammontree", "ajean"]
 files:
   - _underscore/_underscore.php
@@ -371,6 +371,7 @@ multi-file UI components (`.php`/`.html`/`.css`/`.js`) invoked as `<_ComponentNa
 
 ## Gotchas
 
+- **⚠ `_Environment::isDebugMode()` (Environment.php) returns TRUE when the `[_underscore]` config group is missing** (fail-safe to debug). Anything gated on it silently turns off in a prod config lacking the group — e.g. worker2 NetSuite order sends return `skippedDebugMode` and still record success. Prod must set `[_underscore]` with debug off. See [NetSuite sales-order push](../worker2/features/netsuite-salesorder-outbound-push.md).
 - **`FIELD_STORAGE` writes were silently dropped platform-wide (fixed 2026-07, `Model.php`).** Two
   bugs: (a) `buildSqlFieldValue()` read the field via `$this->$field`, which for a storage field
   triggers `__get()` → a disk/S3 **refetch** that overwrote the just-assigned value before `save()`

package/knowledge/2.0/apps/_underscore/features/client-user-contactid-required.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-21
-owners: [jcardinal]
+updated: 2026-09-23
+owners: [jcardinal, mhammontree]
 files:
   - _underscore/Model/Client/User.php
   - worker2/Worker/Sync/ActiveDirectory.php
@@ -53,15 +53,19 @@ The interceptor covers the **generic api2 CRUD** for everyone. The dedicated cre
 | ClickUp user cache | `worker2/Worker/Netsuite/Opportunity.php` `cacheClickupUser()` (raw SQL) | True | **fixed** — `ensureTrueContactId` |
 | Store SAML/hash SSO | `store/_/app/framework.php` | Prudential | **fixed** — see [prudential-sso-login](../../../1.0/apps/store/features/prudential-sso-login.md) |
 | SAML gateway | `_Model_Rate_ClientAuthentication` (saml) | Rate | already sets it |
-| Compass PeopleFile | worker2 (raw SQL) | Compass | already sets it |
+| Compass PeopleFile | worker2 (raw SQL) | Compass | **fixed 2026-09-23** — it set `contactId` *after* the insert; see below |
 
 Northwell ServiceNow users arrive via api2 eBonding (`_Model_Northwell_Ticket` interceptors), not a dedicated worker, so the interceptor covers them.
 
 ## Gotchas
 
+- **⚠ Create the Contact BEFORE the `Users` INSERT — a create-then-`UPDATE` path breaks the moment the column goes NOT NULL.** Omitting `contactId` from an INSERT column list makes MySQL write `0`, which the FK rejects (`Cannot add or update a child row ... CONSTRAINT Users_ibfk_1`). Compass's PEOPLE importer failed in prod this way on 2026-09-22, a full day after the tenant migration ran — audit every remaining raw-SQL user-insert path for the same ordering, not just for "does it set contactId eventually". Worked fix: [Compass PEOPLE-file user lifecycle](../../../clients/compass-usa/features/people-file-user-lifecycle.md).
+- **⚠ Do not read the new Contact's id with `LAST_INSERT_ID()` through `_Query`.** `_Query` routes SELECTs to the read host and `LAST_INSERT_ID()` is per connection, so it can return `0` — which is now an FK violation rather than a harmless null. Use `mysqli_insert_id` on the write/transaction connection and reject an id `<= 0`. See [Per-client database connections](./per-client-database-connections.md).
+
 - **⚠ A reconstructed `new _Model_Client_User($id)` does NOT carry `contactId`.** In `ActiveDirectory.php` the AD sync reads the existing `contactId` from the **bulk SELECT** and only creates a contact when it is truly missing. A naive `empty($user->contactId)` guard against a freshly reconstructed model reads null even when the row has a contact — and would **mint a duplicate contact every sync**. Trust the SELECT'd value, not the rehydrated model property.
 - **⚠ Set `primaryContactEmailAddressId` with a second server-side load+save, never a nested payload.** The nested singular-FK write re-parents (CREATE) or echoes null (UPDATE).
 - **Interceptor no-ops on a user with no email** — a no-email straggler gets no Contact from this path (the backfill migrations handle those name-only, per client). It is why the fan-out `NOT NULL` skips a client that still has a no-email residual (see [rerunnable-additive-inserts](../../dbchanges2/features/rerunnable-additive-inserts.md)).
 
 ## Change history
+- 2026-09-23 — Corrected the origin map: the Compass PEOPLE importer did **not** safely set `contactId` — it inserted `Users` first and linked afterwards, so the NOT NULL rollout broke it in prod (TRUE-82230). Added the write-order and `LAST_INSERT_ID()` gotchas for every raw-SQL creation path. (mhammontree)
 - 2026-09-21 — Initial. Decided `Client_*.Users.contactId` goes NOT NULL platform-wide (CTO Option B); built the shared `_Model_Client_User::postPost` interceptor (Core row: recordId 2, clientId+apiId NULL) to create+link a Contact for api2-created users; fixed the worker2 AD-sync and `cacheClickupUser` True paths; recorded the origin map and the reconstructed-model `contactId` gotcha. (jcardinal)

package/knowledge/2.0/apps/_underscore/features/per-client-database-connections.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
+updated: 2026-09-23
 owners: ["dfranks", "jcardinal", "mhammontree", "apeterson", "kyalamarthi", "bala"]
 files:
   - _underscore/Database.php
@@ -59,6 +59,9 @@ When `_underscore` serves a request for a client it opens **three distinct per-c
 
 ## Gotchas
 
+- **⚠ NEVER read `LAST_INSERT_ID()` (or any other per-connection session value) through `_Query`.** `_Query` defaults `_isReadHostEnabled = true` (`Query.php:8`) and routes SELECTs to `CONNECTION_READ` (`Query.php:273-276`). `LAST_INSERT_ID()` is scoped to the connection that did the INSERT, so a read-host SELECT returns **0** — silently wrong, and now an FK violation wherever the id is used as a foreign key. Use `mysqli_insert_id` on the write/transaction connection and reject `<= 0`. It is not biting today only because most client registrations leave `writeHost`/`readHost` null, and `Database.php:488` then points READ and WRITE at the **same** `mysqli` handle (so raw `mysqli_query` and `new _Query(...)` share one connection and one transaction). Configuring a real read host for any client would break every such call at once. Worked example: [Compass PEOPLE-file user lifecycle](../../../clients/compass-usa/features/people-file-user-lifecycle.md).
+- **Raw `mysqli_query` bypasses `_Query`'s automatic query-cache reset.** After a hand-rolled write, call `_Database::resetQueryCache($dbName)` yourself or later model reads serve stale rows.
+
 - **NEVER build a client's database name as `'Client_' . $clientIdentifier`.** They diverge in production (`Compass_Usa` → `Client_Compass`). Resolve `Core.Clients.clientDatabaseId` → `Core.Databases.name`. This mirrors the log-database resolution already done in `_underscore`'s `Email.php`. A string-built name fails only for the clients whose names happen to diverge, so it passes local testing and breaks in production.
 - **The same rule applies to the LOG database: never build `'Logs_' . $clientIdentifier`.** Resolve `Core.Clients.logDatabaseId` → `Core.Databases.name` (`Compass_Usa` → `Logs_Compass`). A string-built log-DB name silently targets a schema that does not exist.
 - **`_Database::registerClientDatabases()` is unsafe for a loop over ALL clients.** It INNER JOINs the client database *and* archive database alongside the log database, so a client missing either row drops out of the result set entirely — and the method then dereferences the null row (`$database->clientId`) and throws. It also opens three connections per client when a caller may need only one. For an all-client fan-out, run a **log-database-only** variant with **LEFT OUTER JOINs** and report clients that resolve to nothing, rather than letting them vanish. Worked example: [All-Client Email Queue Monitor](../../worker2/features/all-client-email-queue-monitor.md).
@@ -86,3 +89,6 @@ Methodology lesson — why the wrong conclusion was reached: the model-class com
 - [Running a 2.0 app locally (browser end-to-end)](../workflows/running-a-2.0-app-locally.md) — the full local-stack runbook these three connections are one requirement of.
 - [NetSuite → TOGa Supply per-client sync](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md) — the work that surfaced this.
 - [Re-pointing a DB alias mid-request](./database-alias-repointing.md)
+
+## Change history
+- 2026-09-23 — Added the read-host routing trap: `_Query` sends SELECTs to `CONNECTION_READ`, so `LAST_INSERT_ID()` read through `_Query` can return 0; noted that null `writeHost`/`readHost` currently collapses both to one handle, and that raw `mysqli_query` needs a manual `resetQueryCache()`. (mhammontree)

package/knowledge/2.0/apps/worker2/features/netsuite-salesorder-outbound-push.md

@@ -6,8 +6,8 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
-owners: ["bala"]
+updated: 2026-09-23
+owners: ["bala", "jcardinal"]
 files:
   - worker2/Worker/Netsuite/SalesOrder.php
   - test/@Bala/tests/netsuite_salesorder_payload_tests.php
@@ -89,6 +89,14 @@ Flow:
    The internalId is written back to `SalesOrders.c_netsuiteInternalSalesOrderId` by the shared
    `writeBackNetSuiteId()` (three paths now save it).
 7. `dryRun = true` builds and returns the payload without calling NetSuite.
+8. **Non-prod send guard (2026-09-23).** `doCreate`/`doUpdate` check `_Environment::isDebugMode()`
+   after the dry-run return, before any NetSuite read/write or Toga write-back; if true they return
+   `{"action":"skippedDebugMode","intendedAction":"create|update","salesOrderUuid":…}`
+   (`buildDebugModeSkipResult()`). Covers CreateNetSuite, CreateNetSuiteFromTransferOrder,
+   UpdateNetSuite, Sync (all funnel through doCreate/doUpdate). Job records success. `dryRun` still
+   runs in debug mode. Inbound webhooks unaffected. Why: only one NetSuite env (prod); non-prod
+   worker2 was sending orders to it. Callers: `_underscore` Model/Client/TransferOrder.php,
+   Model/Adyen/SalesOrder.php, Model/Elite/SalesOrder.php via `_Worker::runTask`.
 
 ### The shared builder now serves two order types — the changes were additive and defaulted
 
@@ -230,6 +238,10 @@ the transfer-order work.
 
 ## Gotchas
 
+- **⚠ `_Environment::isDebugMode()` returns TRUE when the `[_underscore]` config group is missing**
+  (fail-safe to debug). A prod config missing that group, or with debug on, silently stops ALL
+  NetSuite order sends — jobs still show success with `skippedDebugMode`. Prod must set
+  `[_underscore]` with debug off. Seeing `skippedDebugMode` in prod `WorkerJobs` = config problem.
 - **⚠ Still unverified: can SuiteQL FILTER on `transaction.externalid` in this account?** A `created`
   result **cannot distinguish** *"the lookup ran and found nothing"* from *"the lookup is broken and
   always finds nothing."* This project has already hit a NetSuite column that could be `SELECT`ed but

package/knowledge/2.0/apps/worker2/workflows/running-worker2-locally.md

@@ -6,11 +6,12 @@ project: Worker
 client: shared
 type: workflow
 status: active
-updated: 2026-09-16
-owners: ["kyalamarthi", "bala"]
+updated: 2026-09-23
+owners: ["kyalamarthi", "bala", "mhammontree"]
 files:
   - worker2/index.php
   - worker2/_.php
+  - _underscore/Email.php
   - library/_.php
   - test/@dave/nsq2.php
   - worker2/composer.json
@@ -128,6 +129,10 @@ NetSuite or to `Forecast`.
 
 ## Gotchas
 
+- **⚠ Locally, worker2's `Core` resolves to the 1.0 `Core` database, not the 2.0 one.** `worker2/_.php:20` has `const DB_CORE = 'Core';` and `Core` is never explicitly registered, so the schema name is used literally. On a dev machine the 2.0 tables live in **`Core_2`** (48 tables) while `Core` is the 1.0 schema (10 tables) — symptom: `Table 'core.workerjobs' doesn't exist`. Workaround: flip `DB_CORE` to `'Core_2'` locally and **revert before committing**.
+- **That workaround is incomplete — `_underscore/Email.php:435` hardcodes the literal prefix `FROM Core.Clients`.** So the summary-email step still throws `Table 'core.clients' doesn't exist` no matter what `DB_CORE` says. In the Compass PEOPLE cron that step runs **last**, after both tenants commit, so the data work is unaffected — but do not read the trailing exception as a failed run.
+- **⚠ A stale local client database silently invalidates the test.** A local tenant that predates a migration can make broken code **pass** locally — e.g. local `Client_Compass` still had `contactId` NULLABLE, so a missing FK value was accepted where prod's `NOT NULL` turns it into `0` and a constraint error. Before testing anything schema-sensitive, drop and reload the tenant from production and **re-verify the constraint/index actually survived the copy**.
+
 - **The ad-hoc SuiteQL runner `test/@dave/Junk Drawer/NetSuite/nsq.php` cannot start — stale bootstrap.**
   Its `require` walks three `../` from its current folder, which resolves to a **nonexistent
   `test/worker`** (the file was moved after it was written), so it dies before any query. Replaced by
@@ -174,3 +179,6 @@ NetSuite or to `Forecast`.
 - [Repairing non-prod metadata drift](../../dbchanges2/workflows/nonprod-metadata-drift-repair.md).
 - [`ENVIRONMENT` decides the `_underscore` branch and Config file](../../api2/features/environment-variable-drives-underscore-branch.md)
   — the api2 sibling of steps 2–3.
+
+## Change history
+- 2026-09-23 — Added three local-run traps found on TRUE-82230: worker2's literal `DB_CORE = 'Core'` hits the 1.0 schema locally (2.0 lives in `Core_2`); `_underscore/Email.php:435` hardcodes `FROM Core.Clients` so the summary-email step throws regardless; and a stale local client DB can make broken code pass (reload from prod and re-verify constraints). (mhammontree)

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

@@ -17,8 +17,8 @@ project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-09-21
-owners: [jcardinal, bala, tcox, apeterson, ajean]
+updated: 2026-09-23
+owners: [jcardinal, bala, tcox, apeterson, ajean, mhammontree]
 files: []
 related:
   - ../compass-usa/profile.md
@@ -29,6 +29,7 @@ related:
   - ../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/persona-model-and-levy-gating.md
   - ../compass-usa/features/isfulfillable-data-quality-and-type-rule.md
   - ../compass-usa/features/mits-sales-order-transmission-alerting.md
   - features/french-order-email-localization.md

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

@@ -6,12 +6,15 @@ project: Worker
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-09-16
-owners: [bala, ajean]
+updated: 2026-09-23
+owners: [bala, ajean, mhammontree]
 files:
   - worker2/Worker/Client/Compass/PeopleFile.php
 related:
   - ./persona-model-and-levy-gating.md
+  - ../../../2.0/apps/_underscore/features/client-user-contactid-required.md
+  - ../../../2.0/apps/_underscore/features/per-client-database-connections.md
+  - ../../../2.0/apps/worker2/workflows/running-worker2-locally.md
   - ../../../1.0/apps/tools/features/compass-user-persona-admin.md
   - ./approval-decision-flow.md
   - ./stranded-approval-reassignment.md
@@ -50,6 +53,16 @@ where `5` is `CONTACT_UNLINK_GRACE_DAYS`. The window exists for the `contactId`-
 
 **Username casing is NOT a contributing cause.** Both the lookup build and the post-insert refresh already `strtolower()` the `c_hrEmpUsername` key, so a casing change in the HR file cannot produce a miss. Do not look there.
 
+### Contacts are created BEFORE the Users insert (FK order, fixed 2026-09-23)
+`Client_Compass.Users.contactId` and `Client_CompassCanada.Users.contactId` are **NOT NULL with FK `Users_ibfk_1` → `Contacts(id)`** (added 2026-09-22; platform rule: [Client Users require a contactId](../../../2.0/apps/_underscore/features/client-user-contactid-required.md)). The importer used to insert `Users` first *without* `contactId` in the column list (MySQL wrote `0`), then create the Contact and link it with an `UPDATE`. Under the FK that INSERT fails outright.
+
+Current order for a **new** user:
+1. `insertContactsForNewUsers()` — creates the Contact for every new user and stamps the id onto the staged row. It **throws** if a staged user has no contact rather than letting a `0` through.
+2. The `Users` batch INSERT, with `contactId` now in the column list.
+3. `executeContactsInserts()` Step 2's `UPDATE` covers **existing** users only.
+
+A `_isNewUser` flag on each staged contact is what separates the two paths; existing users missing a contact keep the old create-then-`UPDATE` route. `insertContact()` is the shared helper both use.
+
 ### Order of operations inside a single run
 Within one job the **inserts (and their id refresh) run before the inactivation batch**. That ordering is the hook point for anything that has to bridge an old row to a new one: at insert-refresh time the **new row already has its id** and the **old row is still findable**. A deactivation-time hook would be worse — by then the new row's relationship to the old one has to be rediscovered, and the deactivation path has no model hooks at all.
 
@@ -83,7 +96,7 @@ The insert-time hook designed 2026-08-12 was built and grew into a reusable engi
 - **A duplicate account strands approvals, but not email.** The approval gate matches on user id, so a decision assigned to the old row is invisible to the same human's new account — while the notification email still arrives, because both rows carry the same address. Visible symptom: a person chased to approve an order they cannot see. Detail: [Approval-Decision Flow](./approval-decision-flow.md).
 - **Widening the lookup window is not a free fix.** Removing or extending the grace window would stop new duplicates at source, but also changes which rows the `contactId`-unlinking logic considers and would begin reactivating long-dead accounts. Deliberate deferred item, not 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.
-- **⚠ `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`. Running with `DRY_RUN = true` still removes the PEOPLE file from `sftp.goagilant.com` and destroys the input you were inspecting. Take your own copy first, or set `TEST_MODE`.
+- **⚠ `TEST_MODE` and `DRY_RUN` do different jobs and NEITHER alone is safe — set BOTH to test.** `TEST_MODE` reads a local file instead of SFTP and skips the SFTP delete, but does **not** stop a single database write. `DRY_RUN` skips the DB writes but does **not** stop the SFTP delete — a "safe" dry run still removes the PEOPLE file from `sftp.goagilant.com` and destroys the input you were inspecting. `DRY_RUN` also skips the whole contact/user insert path (it sits inside `if (!self::DRY_RUN)`), so a dry run **cannot** test that code and reports a misleading success. `TEST_FILE_PATH`'s committed value (`//var//www//html//...`) is not where the app lives on Elastic Beanstalk (`/var/app/current/...`).
 - **⚠ 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. 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,000 rows with no index on `c_hrEmpPersonnelNbr`, `email`, `c_hrEmpUsername`, or `isActive`.** Any per-row lookup against those columns is a full scan — `EXPLAIN` returns `type=ALL`, 176,018 rows, no possible keys (re-confirmed prod 2026-09-02, same on `Client_CompassCanada`). An index migration is recommended and **still not done**. **The blank-client template is not a safe proxy for this schema**: `dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql` declares `UNIQUE KEY email (email)`, and Compass has diverged from it. Check the live tenant, never the template.
@@ -95,6 +108,11 @@ The insert-time hook designed 2026-08-12 was built and grew into a reusable engi
 - **⚠ The Tools admin's edit block covers only the original four addresses, not the two CA-only ones.** The protected set grew to six in worker2 on 2026-09-16; the `tools` block list was not changed and was not re-checked. Until it is, someone can edit the email of a CA-protected user in [Tools Compass admin](../../../1.0/apps/tools/features/compass-user-persona-admin.md) and silently drop them out of the protected set — because the match is on email, not id.
 - **⚠ Adding a new "always keep this person active" rule means touching exactly two places.** `executeForTenant()`'s inactivation loop is the only `isActive = 0` writer, and `ensureCrossRegionUsersActive()` is the post-run sweep. Guard both and the requirement is covered; guard only the loop and the post-run sweep still decides the final state; guard only the sweep and the user flickers inactive between the two steps.
 
+- **⚠ A whole tenant run is ONE transaction, and US runs first — so a US exception means Canada never executes at all.** Any throw rolls back everything for that run: inserts, updates, reactivations, **deactivations**, personas, roles and approval reassignment. The 2026-09-22 FK failure blocked both tenants for a day this way. Rollback is clean (proven: a run that died on `Users_Personas` after the `Users` insert left 0 rows behind), and the exception aborts **before** the SFTP delete, so the input file survives and the next run reprocesses it.
+- **⚠ Read `LAST_INSERT_ID()` on the write connection, never through `_Query`.** `_Query` routes SELECTs to the read host, and `LAST_INSERT_ID()` is per connection — so it would return `0`, which the `contactId` FK now rejects. `insertContact()` uses `mysqli_query` + `mysqli_insert_id` on the transaction connection, throws if the id is `<= 0`, and calls `_Database::resetQueryCache($dbName)` by hand because it bypasses `_Query`'s automatic cache reset. Framework detail: [Per-client database connections](../../../2.0/apps/_underscore/features/per-client-database-connections.md).
+- **A "successful" run is not proof a file was processed.** The SFTP picker is FIFO (oldest first) and handles **one** file per run, and an **empty SFTP directory is a silent success** — the job just returns. The PEOPLE file is a full snapshot of the active roster (80,805 usernames vs 75,133 active users on 2026-09-23), not a delta.
+- **⚠ A stale local client DB silently invalidates a test of this cron.** Local `Client_Compass` had `contactId` NULLABLE, so the *old broken code passed locally* — a NULL FK is allowed; only prod's NOT NULL turns the missing column into a `0`. Local also lacked persona 35 and still called persona 1 "All". Drop and reload both tenants from prod, then re-verify the constraint survived the copy, before trusting any result. Local-run mechanics: [Running worker2 locally](../../../2.0/apps/worker2/workflows/running-worker2-locally.md).
+
 ## Related
 - [Persona Model & Levy-Sector Gating](./persona-model-and-levy-gating.md) — the persona/catalogue half of the same cron.
 - [Compass Approval-Decision Flow](./approval-decision-flow.md) — what a duplicate account breaks downstream.
@@ -102,3 +120,6 @@ The insert-time hook designed 2026-08-12 was built and grew into a reusable engi
 - [Record Change Audit Log](../../../2.0/apps/_underscore/features/record-change-audit-log.md) — why the importer's raw writes leave no audit trail.
 - [Compass USA profile](../profile.md)
 - [Users.email as login identity](../../../2.0/apps/_underscore/features/user-email-as-identity-and-password-reset.md)
+
+## Change history
+- 2026-09-23 — **Fixed the `Users.contactId` FK write order (TRUE-82230).** Jeff's `NOT NULL` + `Users_ibfk_1` on both tenants broke the importer from 2026-09-22 09:15 (last good run 2026-09-21); the whole run rolled back and Canada never executed. New `insertContactsForNewUsers()` creates the Contact before the `Users` batch and puts `contactId` in the INSERT column list; existing users missing a contact keep the create-then-UPDATE path. Also recorded: `LAST_INSERT_ID()` must be read on the write connection (not `_Query`); `TEST_MODE` vs `DRY_RUN` neither being safe alone; the FIFO/one-file/empty-is-silent-success facts; and that a stale local DB hides this class of bug. Verified against prod-reloaded local schemas: 80 new US / 17 new CA users, 0 with null-or-0 `contactId`. (mhammontree)

package/knowledge/clients/compass-usa/features/persona-model-and-levy-gating.md

@@ -6,8 +6,8 @@ project: Worker
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-09-17
-owners: [bala, ajean]
+updated: 2026-09-23
+owners: [bala, ajean, mhammontree]
 files:
   - worker2/Worker/Client/Compass/PeopleFile.php
 related:
@@ -130,7 +130,21 @@ persona 1 *removed*, non-Levy users have it *added*; there is no Non-Levy person
 confirmed **unreachable via the Levy path**: `Client_CompassCanada` has **zero** locations with
 `c_erpEntityId = 'K00000'` and **zero** users with either hardcoded Levy personnel number.
 
-VIP (35) and CDL (30) handling is orthogonal and applies to both tenants unchanged.
+**⚠ Persona ids mean DIFFERENT things per tenant — and the VIP/CDL branches are gated inconsistently.**
+
+| id | `Client_Compass` (US) | `Client_CompassCanada` (CA) |
+|---|---|---|
+| 1 | Base | All |
+| 24 | Levy Purchaser | ESFM - CGC |
+| 30 | Macbook and Surface (CDL) | Foodbuy Member Development |
+| 35 | VIP Role | **does not exist** |
+| 40 | Non-Levy | — |
+
+The constants are named `PERSONA_ID_US_*`, so US-only was the intent, but only one branch enforces it:
+- **Persona 30 is gated** (`$shouldHavePersona30 = $tenantKey === 'US' && ...`). Side effect: for CA the flag is always false, so the `elseif (!$shouldHavePersona30 && $hasPersona30)` delete branch **strips persona 30 from every Canadian user who holds it** — and 30 is a real CA persona. Harmless only because prod `Client_CompassCanada` currently has **0** users on it.
+- **Persona 35 is NOT gated** (`if ($c_isVip)` with no tenant check). A Canadian VIP would hit an FK error on `Users_Personas` for a nonexistent persona and roll back the entire Canada tenant. It has not fired because `$c_isVip` is read from the **file**, not the DB, and the file carries 0 CA VIP rows (2,244 US; `erp_system_id` 2010 = CA, 1001 = US, VIP is column 19) — even though one CA user has `c_isVip = 1` in the `Users` table.
+
+Both are **latent, not live, and not yet fixed** — each needs its own ticket. **Deploy risk:** US used to throw first so Canada never ran; once Canada executes again these branches are reachable.
 
 ## Gotchas
 
@@ -168,6 +182,7 @@ VIP (35) and CDL (30) handling is orthogonal and applies to both tenants unchang
   constants from this file into tickets, docs, or chat transcripts.
 
 ## Change history
+- 2026-09-23 — Recorded the per-tenant persona-id table and two **unfixed** CA gating gaps found while fixing TRUE-82230: persona **35 (VIP) has no tenant check** and would FK-fail on Canada (latent only because the file carries no CA VIP rows), and the persona **30 delete branch strips a real CA persona** from every Canadian user holding it (0 today). Both need their own tickets; both become reachable now that Canada runs again. (mhammontree)
 - 2026-09-17 — **The refactor is live in prod (TRUE-80672) and the persona set changed shape.** It is
   a **three-way** split: Base (1) keeps the 9 kits Levy also held, **Non-Levy is id 40 / number 42**
   (id and number differ — never assume they match), and **Levy (24) now holds only its own 5 kits**.

package/package.json

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