toga-ai 1.0.1111 → 1.0.1112

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

@@ -6,7 +6,7 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-09-16
+updated: 2026-10-22
 owners: [ajean, bala]
 files:
   - tools/_/app/compass.php
@@ -28,14 +28,16 @@ related:
   - ../../../clients/compass-usa/features/persona-model-and-levy-gating.md
   - ../../../clients/compass-usa/features/cost-centers.md
   - ../../../clients/compass-usa/workflows/granting-persona-bundle-access.md
+  - ../../../clients/compass-usa/workflows/granting-api-access.md
+  - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
 ---
 
 ## Summary
 
 Two pages in the Tools `developers` nav folder that let staff do, in a browser, the Compass
 requests that used to mean "email a developer, who writes a `dbchanges2` SQL file": **activate /
-deactivate a Compass user**, **grant a persona**, and (as of 2026-09-04) **fix a user's email,
-phone number and cost center**. Both tenants are covered by one tenant switcher — **US**
+deactivate a Compass user**, **grant a persona**, (as of 2026-09-04) **fix a user's email,
+phone number and cost center**, and (2026-10-22, TRUE-82890) **grant a 2.0 ACL role**. Both tenants are covered by one tenant switcher — **US**
 (`Client_Compass`) and **Canada** (`Client_CompassCanada`).
 
 **This is the first thing in `tools` that WRITES to a client tenant database.** Until now the app
@@ -48,9 +50,9 @@ field-editing work (email / phone / cost center) is PR **tools#14**, branch
 ## Key files / entry points
 
 - **`tools/_/app/compass.php`** — `App_Compass`, all data access for both pages (search, persona
-  resolution, activate/deactivate, grant, and the three field setters).
+  resolution, activate/deactivate, grant, the three field setters, and the role grant).
 - **`tools/mvc/compass/users/{get,post}.php`** — user search + activate/deactivate + grant persona
-  + edit email / phone / cost center.
+  + edit email / phone / cost center + Roles card / `addRole` action.
 - **`tools/mvc/compass/personas/{get,post}.php`** — inspect one persona and who reaches it.
 - **`tools/_/app/nav.php`** — the two nav entries, inside the existing `developers` folder.
 - **`tools/config.production.ini`** — `[database_compass]` / `[database_compasscanada]`, plus the
@@ -67,6 +69,8 @@ field-editing work (email / phone / cost center) is PR **tools#14**, branch
 4. **Inspect a persona** and list who reaches it, from all three sources.
 5. **Grant a persona** — one `INSERT` into `Users_Personas`.
 6. **Edit email, phone number and cost center** (2026-09-04, PR tools#14).
+7. **Grant a role** — Roles card + "Grant role" form; one `Users_Roles` insert (2026-10-22,
+   TRUE-82890). See below.
 
 The "why" column is the point of the tool. Answering "who has persona N" from `Users_Personas`
 alone badly under-reports on Compass, because most users hold their catalogue through their
@@ -113,6 +117,37 @@ rows — see [Cost Centers](../../../clients/compass-usa/features/cost-centers.m
 **before/after persona diff** to be shown and confirmed, because a location change moves the user's
 sector and therefore their catalogue.
 
+### Role grant (TRUE-82890)
+
+`App_Compass::roles()`, `role()`, `rolesForUser()`, `hasRole()`, `addUserToRole()`, plus
+`isSensitiveRole()` / `isBlockedRole()` / `roleNameIn()` over the consts `SENSITIVE_ROLE_NAMES` /
+`BLOCKED_ROLE_NAMES`. Post action `addRole` in `users/post.php`.
+
+1. **Additive only.** Inserts one `Users_Roles` row; never replaces Base / Compass Base (roles
+   resolve as a union — removing one takes access away). **No remove action** — undo is hand SQL.
+2. **Blocked: `API`, `Refresh API`, `Public`.** These are API-key / anonymous roles bound through
+   `Apis_Roles`, not roles for people. Hidden from the dropdown AND refused in both `post.php` and
+   `addUserToRole()`.
+3. **High-access roles need a confirm checkbox:** `Admin`, `SuperUser`, `Developer`,
+   `Agilant - Administrators`, or any role with `coreRoleId > 1`. Name match is trimmed and
+   case-blind. The audit note records `[high-access confirmed]`.
+4. **Resolve the posted `roleId` against that tenant's `Roles` table** — ids differ per tenant
+   (see gotcha). Never hardcode.
+5. **Duplicate-safe insert:** `INSERT ... SELECT ... WHERE NOT EXISTS` + `affectedRows()`.
+   `Users_Roles` has **no unique key on `(userId, roleId)`**, so a double-click would otherwise
+   add a second row.
+6. **Audit row first** (`logChange()`, before the insert); `logFailureRow` on failure.
+
+**Survives the night.** The worker2 PEOPLE cron (`Worker/Client/Compass/PeopleFile.php`) only
+INSERTS `Users_Roles` rows (Base + Compass Base for everyone, Manager for anyone who is some
+user's `supervisorUserId`) and never deletes one — unlike email / phone / cost center /
+activation, which it overwrites.
+
+**Takes effect at the user's next login.** api2 puts the user's roles into the login JWT; a
+signed-in user keeps the old set until they log in again. No ACL cache to clear.
+
+Not browser-tested at write time (no local tools server on the developer's Mac).
+
 ### Access gating is deliberately tighter than the folder
 
 Both pages `requireAuth(['Development Team'])` — narrower than the `developers` folder's own
@@ -147,8 +182,8 @@ reuse the **existing `[database_true]` account** — same client cluster, only `
 ### Schema footprint: none
 
 The tool creates and alters **nothing**. It reads/writes only `Users`, `Contacts` (+ its primary
-email/phone children), `Users_Personas`, `Locations_Personas`, `Locations`, reads `Personas` for
-names, reads `Core.ClientEmailDomains` / `Core.Clients`, and inserts into `Logs_<Tenant>.Record`.
+email/phone children), `Users_Personas`, `Users_Roles` (insert only), `Locations_Personas`,
+`Locations`, reads `Personas` / `Roles` for names, reads `Core.ClientEmailDomains` / `Core.Clients`, and inserts into `Logs_<Tenant>.Record`.
 
 ## Decisions
 
@@ -172,9 +207,19 @@ names, reads `Core.ClientEmailDomains` / `Core.Clients`, and inserts into `Logs_
   `c_erpSystemEntityId` is also copied into `c_hrEmpDirectoryKey` and treated as unique per
   employee. Same one-way-durability shape as the activation gotcha. Detail:
   [Cost Centers](../../../clients/compass-usa/features/cost-centers.md).
+- **2026-10-22 — Role grant: every tenant role except `API`, `Refresh API`, `Public` (ajean,
+  TRUE-82890).** Developer first chose "all roles", then blocked those three after the CTO review
+  flagged them. Additive only, no remove action.
 
 ## Gotchas
 
+- **⚠ `Roles` ids differ per Compass tenant.** Prod `Client_Compass`: Base 1, Developer 2, API 3,
+  Admin 4, SuperUser 5, Contractor 6, Compass Base 7, Manager 8, Agilant - Administrators 9,
+  Public 10, ODP Vendor Items Manager 11, Refresh Orders 12, View Orders 14, Fulfil and Ship 15,
+  View Vendor Items 16, Refresh API 17. Prod `Client_CompassCanada`: Base 1, Developer 2, API 3,
+  Public 4, Admin 5, SuperUser 6, Contractor 7, Compass Base 8, Manager 9,
+  Agilant - Administrators 10, Refresh Orders 11. Match by name or resolve per tenant.
+
 - **⚠ Activating a Compass user is TEMPORARY; deactivating is durable.** Because the
   `c_isKeepActive` flag was dropped from scope, the nightly PEOPLE importer will deactivate anyone
   absent from that day's file — so an activation only sticks if the person is actually in the file.

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

@@ -19,7 +19,7 @@ project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-10-20
+updated: 2026-10-22
 owners: [jcardinal, bala, tcox, apeterson, ajean, mhammontree, rgirish]
 files: []
 related:
@@ -29,6 +29,7 @@ related:
   - workflows/grand-and-toy-asn-backfill.md
   - workflows/copying-a-us-user-into-the-canada-tenant.md
   - features/persona-model.md
+  - ../../1.0/apps/tools/features/compass-user-persona-admin.md
   - ../../2.0/apps/api2/features/cxml-shipnotice-gateway.md
   - ../compass-usa/features/approval-decision-flow.md
   - ../compass-usa/features/stranded-approval-reassignment.md
@@ -266,7 +267,9 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   Canada: 1 Base, 7 **Contractor**, 8 **Compass Base**, 9 Manager. USA: 1 Base, 7 **Compass Base**,
   8 Manager. USA grants the fulfillment records to roles 3 + 7; Canada grants most of them to role 1
   only. Nearly every logged-in Canada user carries role 1, so this is usually invisible — but ~10
-  users hold Compass Base without Base and still hit the gap.
+  users hold Compass Base without Base and still hit the gap. To grant one Canada user a role, use
+  tools `/compass/users` (Canada tenant) — it resolves the id per tenant; see
+  [Compass user/persona admin](../../1.0/apps/tools/features/compass-user-persona-admin.md).
 - **Canada was NOT damaged by the 2026-08-31 cross-client item merge, and is structurally
   immune.** It was **not** in the `duplicate_items_merge_ALL_CLIENTS.sql` client list; it has a
   **single catalog** ("compass"), 0 part numbers in multiple catalogs, and 0 duplicate part

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

@@ -23,7 +23,7 @@ project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-10-21
+updated: 2026-10-22
 owners: [jcardinal, bala, tcox, apeterson, dfranks, akhokhani, ajean, rgirish]
 files: []
 related:
@@ -219,7 +219,9 @@ separate, related client (see its own profile).
   not `id`, and **`Users` has no `username` column** — it is `c_hrEmpUsername`, stored lowercase.
   Super user = `Roles.id 5` added **additively** via `Users_Roles`, never replacing Base /
   Compass Base. **Kit add-on bundles (`BundleItems.childBundleId`) need their own persona grant**
-  and stay `isActive = 0` by design (TRUE-82981, 2026-10-21).
+  and stay `isActive = 0` by design (TRUE-82981, 2026-10-21). A single role grant (USA or Canada)
+  is now self-serve in tools `/compass/users` (Roles card; `API` / `Refresh API` / `Public`
+  blocked) — see [Compass user/persona admin](../../1.0/apps/tools/features/compass-user-persona-admin.md).
 - [Prod ↔ dev-sandbox persona comparison](workflows/persona-population-env-comparison.md) — the
   full-population diff technique, the **join-on-email** rule (`Users.id` means different people per
   environment), and the drift bundles (188/191/242) that mimic a catalogue grant.

package/knowledge/clients/compass-usa/workflows/granting-persona-bundle-access.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: compass-usa
 type: workflow
 status: active
-updated: 2026-10-21
+updated: 2026-10-22
 owners: [bala, ajean]
 files:
   - dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql
@@ -72,7 +72,7 @@ The `personaId <> @personaId` exclusion matters: by the time this phase runs, th
 **`Client_Compass.Users` has no `username` column** — the natural first query fails with `Unknown column 'username'`. The Compass login / personnel username lives in **`c_hrEmpUsername`**, stored **lowercase**: people quote it uppercase ("KINGK01") but the row says `kingk01`. Look users up by `email` or `c_hrEmpUsername` (lowercased), which is also how the nightly PEOPLE cron matches them — see [PEOPLE-File User Lifecycle](../features/people-file-user-lifecycle.md).
 
 ### Making someone a super user
-There is **no `isSuperUser` flag on `Users`** — it is a role row. `Client_Compass.Roles.id` **5**, name **`SuperUser`** (113 holders as of 2026-08-26), granted **additively** through `Users_Roles (userId, roleId)`, which is unique on the pair. **SuperUser is never a replacement for the base roles.** The established prod pattern for a Compass super user is **Base (1) + SuperUser (5) + Compass Base (7)**, optionally **+ Manager (8)**. Role permissions resolve as a **union** (see [ACL Permission Chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md)), so adding role 5 while removing 1 or 7 takes access *away*.
+There is **no `isSuperUser` flag on `Users`** — it is a role row. `Client_Compass.Roles.id` **5**, name **`SuperUser`** (113 holders as of 2026-08-26), granted **additively** through `Users_Roles (userId, roleId)`, which has **no** unique key on the pair (guard the insert with `WHERE NOT EXISTS`). A single role grant needs no SQL: use the tools `/compass/users` Roles card — [Compass user/persona admin](../../../1.0/apps/tools/features/compass-user-persona-admin.md). **SuperUser is never a replacement for the base roles.** The established prod pattern for a Compass super user is **Base (1) + SuperUser (5) + Compass Base (7)**, optionally **+ Manager (8)**. Role permissions resolve as a **union** (see [ACL Permission Chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md)), so adding role 5 while removing 1 or 7 takes access *away*.
 
 ### Verify the way the ACL actually resolves personas
 A user's **effective** persona set is three UNIONed sources, not just `Users_Personas`:

package/package.json

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