toga-ai 1.0.823 → 1.0.824

package/knowledge/1.0/apps/tools/features/compass-user-persona-admin.md

@@ -6,8 +6,8 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-09-04
-owners: [ajean]
+updated: 2026-09-16
+owners: [ajean, bala]
 files:
   - tools/_/app/compass.php
   - tools/mvc/compass/users/get.php
@@ -101,6 +101,10 @@ conditions of the decision below — **do not remove one without re-opening it**
    (the same human on two `Users` rows).
 5. The four `ensureCrossRegionUsersActive()` addresses are **blocked as both source and target**
    (`isCrossRegionProtectedEmail()`), because that hardcoded worker2 list matches on email.
+   **⚠ Out of date as of 2026-09-16:** worker2 split that list into six addresses
+   (`ALWAYS_ACTIVE_EMAILS_BOTH` + `ALWAYS_ACTIVE_EMAILS_CA`), so the two new
+   `@compassdigital.io` Canada-protected addresses are **not** blocked here yet. See
+   [PEOPLE-File User Lifecycle](../../../clients/compass-usa/features/people-file-user-lifecycle.md).
 6. The **audit row is written before the write**, on its own connection (see the transaction
    gotcha below).
 
@@ -191,9 +195,14 @@ names, reads `Core.ClientEmailDomains` / `Core.Clients`, and inserts into `Logs_
   ~178,615 of 178,616 `Client_Compass` rows, so the client id cannot be derived from the user row.
   See [Compass Canada profile](../../../clients/compass-canada/profile.md).
 - **A cross-region user still needs a code change and a deploy.** The only durable way to hold one
-  active is the hardcoded four-address list in `ensureCrossRegionUsersActive()` in
+  active is the hardcoded list in `ensureCrossRegionUsersActive()` in
   `worker2/Worker/Client/Compass/PeopleFile.php`. This tool does not change that — and because that
-  list matches on **email**, those four addresses are blocked from this tool's email edit entirely.
+  list matches on **email**, those addresses are blocked from this tool's email edit entirely.
+  **As of 2026-09-16 that list is six addresses, not four**: `ALWAYS_ACTIVE_EMAILS_BOTH` (the
+  original four, held active in both tenants) plus `ALWAYS_ACTIVE_EMAILS_CA` (two
+  `@compassdigital.io` US staff held active in `Client_CompassCanada` only).
+  `isCrossRegionProtectedEmail()` here still only knows the original four, so the two new addresses
+  can be edited in this tool and silently lose their protection.
 - **Every user search is a full table scan.** `Client_Compass.Users` has no index on `email`,
   `c_hrEmpUsername`, `c_hrEmpPersonnelNbr` or `isActive` (176k rows; `EXPLAIN` reports `type=ALL`,
   no possible keys). Same on `Client_CompassCanada`. Keep result sets bounded and do not add
@@ -235,12 +244,22 @@ names, reads `Core.ClientEmailDomains` / `Core.Clients`, and inserts into `Logs_
   (`_underscore/Model/Compass/SalesOrder.php:287-305`): it joins
   `INNER JOIN Contacts ON Contacts.id = Users.id`, which should be `Users.contactId`.
 - **worker2** — scope `ensureCrossRegionUsersActive()` to a `Users.id` list instead of matching on
-  email; that would also lift this tool's block on those four addresses.
+  email; that would also lift this tool's block on those addresses.
+- **tools** — extend `isCrossRegionProtectedEmail()` to the two `ALWAYS_ACTIVE_EMAILS_CA` addresses
+  added in worker2 on 2026-09-16, or the block silently under-covers the protected set.
 - **ops** — rotate every secret in `tools/config.production.ini`; consider a least-privilege
   Compass account.
 
 ## Change history
 
+- 2026-09-16 — Recorded that worker2's cross-region protected list **grew from four addresses to
+  six** (`ALWAYS_ACTIVE_EMAILS_BOTH` + `ALWAYS_ACTIVE_EMAILS_CA`), so this tool's
+  `isCrossRegionProtectedEmail()` block now under-covers it: the two new `@compassdigital.io`
+  Canada-protected addresses can still be email-edited here and would silently drop out of the
+  protected set, because the worker2 match is on email. No `tools` code changed. Detail:
+  [PEOPLE-File User Lifecycle](../../../clients/compass-usa/features/people-file-user-lifecycle.md).
+  (bala)
+
 - 2026-09-04 — Added **email, phone and cost-center editing** (PR tools#14,
   `feature/compass-user-field-edits`, **open / not merged / not deployed**): new `App_Compass`
   setters plus the `normaliseEmail` / `normalisePhone` / `emailDomainIsRegistered` /

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

@@ -6,7 +6,7 @@ project: Worker
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-09-04
+updated: 2026-09-16
 owners: [bala, ajean]
 files:
   - worker2/Worker/Client/Compass/PeopleFile.php
@@ -85,6 +85,39 @@ insert-refresh time the **new row already has its id** and the **old row is stil
 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 (see below).
 
+### Always-active protection is per-tenant, and has two layers
+
+A small hardcoded set of people must stay active regardless of what HR sends. Since **2026-09-16**
+that set is split into two class constants on `_Worker_Client_Compass_PeopleFile`:
+
+- **`ALWAYS_ACTIVE_EMAILS_BOTH`** — the original four addresses (two `@compass-usa.com`, two
+  `@compass-canada.com`). Held active in **both** `Client_Compass` and `Client_CompassCanada`.
+- **`ALWAYS_ACTIVE_EMAILS_CA`** — two `@compassdigital.io` **Compass USA** staff (usernames
+  `shuttk01` / `racerk01` in `Client_Compass`). Held active in **`Client_CompassCanada` only**.
+  They are allowed to go inactive in the US tenant when the PEOPLE file drops them; that is the
+  requirement, not a bug.
+
+`isEmailAlwaysActive(string $email, string $tenantKey): bool` is the single decision point — a
+lowercased match that returns true for the BOTH list in either tenant, and for the CA list only when
+`$tenantKey === 'CA'`. Two layers consume it:
+
+1. **The inactivation loop** in `executeForTenant()` skips any user whose `Users.email` is
+   protected for that tenant, so the batch `UPDATE ... SET isActive = 0` never lists them.
+2. **`ensureCrossRegionUsersActive()`**, which runs after both tenants have executed and force-sets
+   `isActive = 1` — in both databases for the BOTH list, and in `Client_CompassCanada` only for the
+   CA list.
+
+**Today only layer 2 actually protects the CA-only pair.** In `Client_CompassCanada` both of those
+users have `c_hrEmpUsername = NULL`, and `loadLookups()` keys its map on username — so they never
+enter the map and can never reach the inactivation batch on the Canada side. The loop guard is the
+defence for the day HR gives them a Canada username, not what is holding them active now.
+(Read-only prod check, 2026-09-16.)
+
+**The email match works across a case difference.** `Client_Compass` stores these two addresses
+UPPERCASE while `Client_CompassCanada` stores them lowercase. `Users.email` uses
+`utf8mb4_0900_ai_ci`, a case-insensitive collation, so `WHERE email = '...'` still hits — each
+address resolves to exactly **one** row per database.
+
 ## Gotchas
 
 - **⚠ Deactivation is raw bulk SQL — model hooks never fire.** User inactivation is executed as
@@ -157,16 +190,26 @@ rediscovered, and the deactivation path has no model hooks at all (see below).
   makes the [Tools Compass admin
   pages](../../../1.0/apps/tools/features/compass-user-persona-admin.md) a one-way-durable tool.
 - **`ensureCrossRegionUsersActive()` runs `UPDATE Users SET isActive = 1 WHERE email = X` with no
-  `isActive` filter**, so it reactivates **every** row carrying one of its four hardcoded addresses,
-  dead duplicates included. Verified on prod 2026-09-02: each of the four addresses currently
-  resolves to exactly **one** active row in **both** tenants (zero inactive), so nothing is being
-  resurrected today — but the query would happily do it if a duplicate appeared. That hardcoded list
-  is also still the **only** durable way to hold a cross-region user active, and changing it needs a
-  code change and a deploy per request. **Recommended (not done): scope it to a `Users.id` list
-  instead of matching on email** — matching on email means an email edit silently moves a user in or
-  out of the protected set, which is why the [Tools Compass
-  admin](../../../1.0/apps/tools/features/compass-user-persona-admin.md) blocks those four addresses
-  from being edited at all.
+  `isActive` filter**, so it reactivates **every** row carrying a protected address, dead duplicates
+  included. Verified on prod 2026-09-02 for the original four, and 2026-09-16 for the two CA-only
+  addresses: each resolves to exactly **one** row per database, so nothing is being resurrected
+  today — but the query would happily do it if a duplicate appeared. That hardcoded list is also
+  still the **only** durable way to hold a cross-region user active, and changing it needs a code
+  change and a deploy per request. **Recommended (not done): scope it to a `Users.id` list instead
+  of matching on email** — matching on email means an email edit silently moves a user in or out of
+  the protected set, which is why the [Tools Compass
+  admin](../../../1.0/apps/tools/features/compass-user-persona-admin.md) blocks the protected
+  addresses from being edited at all.
+- **⚠ 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 in the whole class, 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.
 
 ## Remediation — BUILT 2026-08-20
 
@@ -197,6 +240,24 @@ question is now contained rather than blocking.
 
 ## Change history
 
+- 2026-09-16 — **Made the always-active protection tenant-aware.** Two Compass USA staff
+  (`@compassdigital.io`, usernames `shuttk01` / `racerk01`) exist in **both** tenants, but the
+  PEOPLE file lists them only as US rows (`c_erpSystemId` 1001), so they were routed to
+  `Client_Compass` alone and had no protection on the Canada side. Requirement: they may go inactive
+  in the USA per the file, but must **always** stay active in Canada. Split the previously
+  undocumented single hardcoded list into `ALWAYS_ACTIVE_EMAILS_BOTH` (the original four) and
+  `ALWAYS_ACTIVE_EMAILS_CA` (the two new ones), added
+  `isEmailAlwaysActive(string $email, string $tenantKey): bool` as the single lowercased decision
+  point, and wired it into **both** the `executeForTenant()` inactivation loop (skip protected
+  users) and `ensureCrossRegionUsersActive()` (both DBs for BOTH, `Client_CompassCanada` only for
+  CA). Prod read-only findings: in `Client_CompassCanada` both users have `c_hrEmpUsername = NULL`,
+  so they never enter `loadLookups()`'s username-keyed map and **cannot** reach the Canada
+  inactivation batch at all — the post-run sweep is what actually protects them today, and the loop
+  guard is defence for the day they get a Canada username. Also confirmed the two tenants store
+  these addresses in different case (US uppercase, CA lowercase) and the email match still works
+  because `Users.email` uses the case-insensitive `utf8mb4_0900_ai_ci` collation, one row per
+  address per database. Not committed or pushed — worker2 working tree only. (bala)
+
 - 2026-09-04 — Prod-verified the **full index list** on `Users` in both tenants and recorded the
   load-bearing consequence: **there is no `UNIQUE KEY` on `email`** (and no index on
   `c_hrEmpUsername` / `c_hrEmpPersonnelNbr` / `isActive`), so the database silently accepts duplicate

package/package.json

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