toga-ai 1.0.1071 → 1.0.1073

package/knowledge/2.0/apps/_underscore/features/note-record-authorship.md

@@ -16,6 +16,7 @@ files:
   - _underscore/Model/Client/UnitNote.php
   - _underscore/Model/Client/ServiceRequestNote.php
   - _underscore/Model/Client/PartRequestNote.php
+  - _underscore/Model/Client/UserNote.php
 related:
   - ../../toga-blox/features/add-notes-template.md
   - ./case-status-and-stage-gate.md
@@ -63,10 +64,11 @@ Before building anything that shows or filters by note author:
 
 - **`contactId` on a `*Notes` model is an unwritten FK — treat it as always NULL.** Seven models, zero writers.
 - **A notes list UI has no author to show.** Design for it, or the field silently renders blank for every row.
-- **Exception — `CaseNotes` (2026-10-15), `CustomerNotes` and `ContactNotes` (2026-10-17) have a real author:** `authorUserId` stamped in `::save()` from `_Model::getRequestUserId()`. Copy that pattern for the real fix. The `save()` body is now copied 3 times (Case, Customer, Contact) — move it to a shared trait/base before a 4th copy. See [Case status + stage gate](./case-status-and-stage-gate.md), [Customer related records](./customer-locations-files-notes.md), [Contact related records](./contact-notes-files-types.md).
+- **Exception — server-stamped author:** `CaseNotes`, `CustomerNotes`, `ContactNotes`, `IssuerNotes`, `CertificationNotes`, `AttributeNotes`, `UserNotes` carry `authorUserId`, stamped in `::save()` from `_Model::getRequestUserId()` (write-once). Copy that pattern for the real fix. The `save()` body is now copied 7 times — **consolidation debt:** move it to a shared trait/base before adding another. See [Case status + stage gate](./case-status-and-stage-gate.md), [Customer related records](./customer-locations-files-notes.md), [Contact related records](./contact-notes-files-types.md).
 - **`dtStamp` is `FIELD_DATETIME_CREATED`** — stamped by the ORM on insert, the only provenance a note actually carries.
 
 ## Change history
+- 2026-10-17 — UserNotes added; seven author-stamped note models now copy one save() body (TRUE-82872). (jcardinal)
 - 2026-10-17 — ContactNotes added as third server-stamped-author note model; save() body is a consolidation candidate (TRUE-82871). (jcardinal)
 - 2026-10-17 — CustomerNotes added as a second server-stamped-author note model (TRUE-82870). (jcardinal)
 - 2026-10-15 — Noted CaseNotes as the first note model with a server-stamped author. (jcardinal)

package/knowledge/2.0/apps/_underscore/features/record-activity-timeline.md

@@ -32,7 +32,8 @@ client `AclRecordScripts`. Data source: [record change audit log](record-change-
 
 - **Roots** = `ROOT_ACTIVITY_SURFACE_SLUGS` (route → activity Surface slug): `tickets` →
   `ticket-activity`, `units` → `asset-activity`, `cases` → `case-activity`, `service-requests` →
-  `service-request-activity`, `customers` → `customer-activity`, `contacts` → `contact-activity`. Any other route → 400. **A new root = one map entry + its Surface
+  `service-request-activity`, `customers` → `customer-activity`, `contacts` → `contact-activity`,
+  `issuers`, `certifications`, `attributes`, `users` → `<singular>-activity`. Any other route → 400. **A new root = one map entry + its Surface
   (`dbchanges2` `Core/`).** Engine (`Source` reads Logs, `Reader` checks as the reader through api2)
   is generic; no new client ACL needed for a new root.
 - **Children:** `Logs.RecordParent`, level by level, max `Source::MAX_DEPTH` (3) levels and
@@ -45,7 +46,8 @@ client `AclRecordScripts`. Data source: [record change audit log](record-change-
      `isVisible = 0`). An UPDATE with no visible field is dropped. Secrets → `{redacted:true}`.
   4. FK values → `{uuid, label[, slug]}`, `{missing:true}`, or `{value:null}` — never a raw id.
 - **CREATE rows of `CREATE_HIDDEN_ROUTES`** (`ticket-notes`, `ticket-note-files`, `unit-notes`,
-  `case-notes`, `service-request-notes`, `customer-notes`, `contact-notes`) are dropped — the host screen merges the notes feed.
+  `case-notes`, `service-request-notes`, `customer-notes`, `contact-notes`, `issuer-notes`,
+  `certification-notes`, `attribute-notes`, `user-notes`) are dropped — the host screen merges the notes feed.
   Note edits/deletes still show.
 - **Paging:** cursor = `Logs.Record` id; `nextCursor` null at the end. Scan bounded
   (`MAX_SCAN_BATCHES` × `SCAN_BATCH_SIZE`); a page cut by the bound still returns a `nextCursor`.
@@ -68,7 +70,11 @@ client `AclRecordScripts`. Data source: [record change audit log](record-change-
   best-effort (same user + short time window). Exact grouping needs a new request-id column
   (schema + api2 change) — not built.
 
+- **`users` root is safe for secrets:** `password` / `ldapDn` are redacted on write (api2
+  `LOG_REDACTED_FIELD_NAMES`) and on read (`isRedactedLogField`).
+
 ## Change history
+- 2026-10-17 — Added root `users` + `user-notes`; listed `issuers` / `certifications` / `attributes` roots already in code (TRUE-82872). (jcardinal)
 - 2026-10-17 — Added root `contacts` + `contact-notes` to `CREATE_HIDDEN_ROUTES` (TRUE-82871). (jcardinal)
 - 2026-10-17 — Added root `customers` + `customer-notes` to `CREATE_HIDDEN_ROUTES` (TRUE-82870). (jcardinal)
 - 2026-10-17 — One-FK rule for parent links; no request id for grouping (TRUE-82889). (jcardinal)

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

@@ -6,12 +6,13 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-10-13
-owners: [bala, ajean]
+updated: 2026-10-18
+owners: [bala, ajean, jcardinal]
 files:
   - _underscore/Model/Client/Logs/Record.php
   - _underscore/Model/Client/Logs/RecordField.php
   - _underscore/Model/Client/Logs/CustomRecordField.php
+  - api2/Component/Api/V2/V2.php
 related:
   - ../../api2/features/request-logging.md
   - ../../../1.0/apps/tools/features/compass-user-persona-admin.md
@@ -62,6 +63,8 @@ Order by `Record.timestamp` for a fixed `(recordId, primaryKeyId)` for the full
 - **A worker doing raw bulk updates is invisible here.** If a job needs auditable effects it must write its own `Record` **note** row explicitly — nothing is automatic. Real example: [Compass PEOPLE-file user lifecycle](../../../../clients/compass-usa/features/people-file-user-lifecycle.md), whose deactivation batch is a raw `UPDATE Users SET isActive = 0 WHERE id IN (...)`.
 - **⚠⚠ `_Model_Client_Logs_Record::addNote()` IS A SILENT NO-OP OUTSIDE api2.** `addNote()` only **stages** rows into the class's static `$_notes` array. The **only** thing that flushes it is api2's `Component/Api/V2/V2.php`. Nothing in `_underscore` and nothing in `worker2` flushes it. So **any worker or cron that calls `addNote()` loses the note entirely** — no error, no warning, no row. Most dangerous mode on this page: the calling code reads as if it audited itself.
   - A worker needing a note must either drain `_Model_Client_Logs_Record::$_notes` itself and INSERT into `Logs_<Tenant>.Record`, or write the `Record` rows directly. Note **`Logs_<Tenant>.Record.clientId` is `NOT NULL`**, and a worker generally has no `$api` to read the client id from — resolve from `Core` (`Clients` JOIN `Databases` on `name`). Known ids: `Client_Compass` = **2** (`Logs_Compass`), `Client_CompassCanada` = **43** (`Logs_CompassCanada`). Applies to **every** client, not just Compass.
+- **⚠ In api2, `addNote()` must come AFTER any `internalRequest` in the same hook.** The internal request's record-log pass clears every note queued before it. Also, a write done through an internal request on **another** model is logged on that model's row only — not on the parent's — so add a note on the parent if its timeline / `_updated` must show it. Reference: [write intent on a PUT](../../api2/features/api-payload-interceptors.md#audited-action-as-a-table-write-the-action-table-pattern).
+- **⚠ `_created` on a record = the EARLIEST `Record` log row** (`V2.php` `loadLogRecordBatch`, `MIN(id)`), not the row's insert. A row created outside the API (SQL seed, migration) has no create log, so `_created` shows **whoever first wrote it through the API**. Use the table's stored `dtCreated` for "when created".
 - **`Record.userId` is a TENANT `Users.id` — but it is NULLABLE, so a staff-actor row IS possible with no schema change** (verified 2026-09-04, correcting the earlier claim that internal-tool writes had no audit home). You cannot express "a `Client_True` staff member did this" in `userId`, so put the staff identity in **`note`**:
   - `recordId` = the `Core.Records` id of the model (**`Users` = 2**), `primaryKeyId` = the target row's id, `clientId` = the tenant's `Core.Clients` id, `userId` = **NULL**, `note` = who did it and what changed.
   - `_Model_Compass_ApprovalDecision` (`_underscore/Model/Compass/ApprovalDecision.php:1344-1366`) already hand-writes exactly this shape — an established pattern.
@@ -75,6 +78,7 @@ Order by `Record.timestamp` for a fixed `(recordId, primaryKeyId)` for the full
 - **Do not paste logged values into tickets or the KB.** `oldValue`/`newValue` and note text routinely contain user emails and other personal data. Reference rows by location; quote the mechanism, not the people.
 
 ## Change history
+- 2026-10-18 — `_created` = earliest log row (seeded rows show first API writer); `addNote()` after `internalRequest`; internal writes log on their own model only (TRUE-82876). (jcardinal)
 - 2026-10-13 — Added PurchaseOrders / PurchaseOrderItems ids and this log as the surviving source once the Api log ages out. (bala)
 
 ## Related

package/knowledge/2.0/apps/_underscore/features/user-email-as-identity-and-password-reset.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-10-14
-owners: [ajean, rgirish]
+updated: 2026-10-17
+owners: [ajean, rgirish, jcardinal]
 files:
   - _underscore/Model/Client/User.php
   - api2/Component/Api/V2/V2.php
@@ -78,6 +78,13 @@ So whoever controls an address that appears on a `Users` row can request, receiv
 - **⚠ The reset lookup has no `isActive` filter and no duplicate handling.** On a tenant that allows duplicate emails, "the user with this address" is whichever row MySQL happens to return first. Do not assume the reset went to the account you were looking at.
 - **⚠ Do not assume the database enforces one email per user.** The 2.0 blank-client template declares `UNIQUE KEY email (email)`, but **live tenants have diverged** — both Compass tenants have no unique key and no index on `email` (prod-verified 2026-09-04). Any code that writes an email must check for a cross-row collision itself. Evidence and the full index list: [PEOPLE-file User Lifecycle](../../../clients/compass-usa/features/people-file-user-lifecycle.md).
 - **⚠ Treat an email write as a security change, not a data change.** Minimum rails for any UI or job that sets `Users.email`: confirm the value twice, validate the domain against `Core.ClientEmailDomains`, refuse when another row in the tenant already holds the address, and write an audit row **before** the update. That is the shape the [Tools Compass admin](../../../1.0/apps/tools/features/compass-user-persona-admin.md) shipped.
+- **⚠ AD sync overwrites `email`, `title`, `phoneNumber` on every run.**
+  `_Model_Client_User::syncFromActiveDirectoryUser()` (~L314) writes them from AD; an app edit to
+  those fields on an AD-synced user is silently reverted (Client_True: 2,788 of 2,791 users have
+  `ldapDn` set, 2026-10-17). Lock those fields in the UI when calc field `_isDirectorySynced` = 1
+  (`ldapDn` non-empty) — use it instead of exposing `ldapDn`.
+- **Client role `Base` cannot write `Users.email`** (RecordField 115 `isWritable` 0 in Client_True /
+  Client_Elite, 2026-10-17). An email edit needs a stronger role — keep it that way.
 - **An email is also a worker matching key.** worker2's `ensureCrossRegionUsersActive()` matches Compass users on **email**, so changing an address can silently remove a user from a hardcoded protected set — a second reason email edits need an explicit block list.
 - **⚠ `_Http::validateJsonWebToken()` checks the signature only, never `exp`.** Any code that trusts
   a JWT must check `exp` itself. Before 2026-10-13, `updatePassword()` did not, so a reset link
@@ -92,6 +99,7 @@ So whoever controls an address that appears on a `Users` row can request, receiv
 - **Never paste real addresses into tickets or the KB.** Reference the mechanism and the column, not the person.
 
 ## Change history
+- 2026-10-17 — AD sync overwrites email/title/phoneNumber (`_isDirectorySynced` lock); Base role cannot write email (TRUE-82872). (jcardinal)
 - 2026-10-14 — Reset token now 30 min and `updatePassword()` rejects expired tokens; documented the two scripted APIs, Public ACL, `Core.Domains` link host, and the BCC / query-string exposure (rgirish)
 - 2026-09-16 — Created: email as login identity and tenant-routing key (ajean)
 

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

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-10-17
+updated: 2026-10-18
 owners: ["mhammontree", "dfranks", "bala", "snaredla", "jcardinal", "rgirish"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -28,6 +28,8 @@ files:
   - _underscore/Model/Client/UserGlobalSetting.php
   - dbchanges2/Core/2026-10-09a - UserGlobalSettingsInterceptors.sql
   - _underscore/Model/Client/CaseRecordRemoval.php
+  - _underscore/Model/Client/Workflow.php
+  - _underscore/Model/Client/WorkflowVersion.php
 related:
   - ./cross-client-data-retrieval.md
   - ../../_underscore/features/record-activity-timeline.md
@@ -289,6 +291,20 @@ Reference: `_Model_Client_CaseRecordRemoval` (TRUE-82889, CTO-reviewed).
 `postPut` **before** the stage gate, and the gate counts only rows that exist after the write —
 never trust a payload flag that says "I will create it".
 
+**Write intent that writes ANOTHER record under the caller's ACL** (TRUE-82876). Reference:
+`PUT /workflows/{uuid} {"status":"ACTIVE","publishDraft":true}` (`_Model_Client_Workflow`):
+1. PRE PUT strips the intent key, locks, runs the checks (e.g. overlap) first.
+2. The second record's write goes through
+   `_Model_Client_Ticket::runInsideRequestContext($api, fn() => _Model_Client_Ticket::internalRequest(...))`
+   — here `PUT /workflow-versions/{draft} {isPublished:1}` — so api2 checks the caller's ACL and that
+   route's `prePut`. Never write the other model directly.
+3. Any refusal throws → `MODEL_SAVE_ERROR` → 400 → `transactionRollback` of `DB_CLIENT`
+   (`V2.php` ~6844-6906, ~2304-2310): the whole PUT is all-or-nothing.
+4. Audit: the internal write is **not** logged on the parent's row. Call
+   `_Model_Client_Logs_Record::addNote(...)` **after** the internal request — its record-log pass
+   clears every note queued before it (see
+   [record change audit log](../../_underscore/features/record-change-audit-log.md#gotchas)).
+
 ### Own-row guards in a PRE interceptor
 
 A PRE hook that limits a user to their own rows must close four bypasses — each found by review on the `user-global-settings` guard (TRUE-82613):
@@ -358,4 +374,5 @@ Refuse API-key callers when the rule is "the signed-in user" (no user on the tok
 - 2026-10-09 — Own-row guards in PRE hooks (alias keys + parent-route bypasses, PRE before field ACL); user-global-settings reference; known open holes. (jcardinal)
 - 2026-10-15 — PRE → POST state hand-off via `$api->passThrough`; detect a real field change, not a resent one (TRUE-82727). (bala)
 - 2026-10-16 — Command keys: strip in `prePut`, park on `passThrough`, act in `postPut`; empty body → `{}` (TRUE-82849). (jcardinal)
+- 2026-10-18 — Write intent that writes another record via internal request (caller ACL, rollback, `addNote` after the call) (TRUE-82876). (jcardinal)
 - 2026-10-17 — "Action table" pattern for audited actions; write intents before a stage gate; new interceptor rows ship in a file run after the code deploy (TRUE-82889). (jcardinal)

package/knowledge/2.0/apps/api2/features/cross-client-data-retrieval.md

@@ -45,7 +45,7 @@ Because client DBs live on **different clusters**, a cross-DB JOIN/UNION is impo
 
 Entry point is `_Component_Api_CrossClient` (`api2/Component/Api/CrossClient/CrossClient.php`), delegated from a guard at the **top** of the `ACTION__LIST` case in `_Component_Api_V2::processRoutePairs()`: when `isCrossClientRequest($httpOptions)` is true (a non-empty `client` option), it calls `handleListing()`, merges result rows into `$outData` and meta into `$this->response->meta`, and breaks. The guard is **inert** on ordinary single-client GETs.
 
-1. **resolveScope** — the caller's entitled clients resolve via the `Users_Clients` bridge (`Users.homeClientUserId` maps one home user to per-client user records across tenant DBs); each target yields a minted per-client identity. This is **serial** — one DB context switch + query per permitted client, on every request including cache hits.
+1. **resolveScope** — the caller's entitled clients resolve via the `Users_Clients` bridge (Records 199 `user-clients`); `mintIdentity()` then picks each target's linked user. Identity model: a **home** row has `homeClientUserId` NULL; a **linked** row in another client DB has `clientId` = home Core client id + `homeClientUserId` = home `Users.id` (`UNIQUE(clientId, homeClientUserId)`). **"Which clients can this user reach" = `Users_Clients`**, not the linked rows — they drift (local data has a linked row with no `Users_Clients` row). This is **serial** — one DB context switch + query per permitted client, on every request including cache hits.
 2. **queryHash** — SHA-256 of the normalized query plus `QUERY_HASH_VERSION`; the cache key. Bump `QUERY_HASH_VERSION` whenever how cached rows are built or ordered changes — it orphans every older result table (v2 = dotted-field sort keys).
 3. **Build lock** — a named `GET_LOCK` over a **fixed-width digest** of client/user/hash.
 4. **Fan out** — a two-phase concurrent HTTP handshake per client (see [encrypted-user-uuid-auth-handoff](./encrypted-user-uuid-auth-handoff.md)): Phase A mints an access token, Phase B issues the authenticated GET.
@@ -145,5 +145,6 @@ Page 1 of 25 still fetches exactly 25; page 254 fetches 500 per pass — ~13 rou
 - [_Model magic-field access](../../_underscore/features/model-magic-field-access.md)
 
 ## Change history
+- 2026-10-17 — Home vs linked user rows; `Users_Clients` is the reach list, linked rows drift (TRUE-82872). (jcardinal)
 - 2026-10-17 — Fetch scope is `client=` OR own token, never both; key multi-client rows by client + record uuid (TRUE-82903). (jcardinal)
 - 2026-10-17 — Internal-request writes must add their own `cacheInvalidations` (TRUE-82889). (jcardinal)

package/knowledge/2.0/apps/api2/features/v2-rest-query-contract.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-10-17
+updated: 2026-10-18
 owners: [tcox, bala, apeterson, jcardinal, rgirish]
 files:
   - api2/Component/Api/V2/V2.php
@@ -69,6 +69,28 @@ controller.
   the join is genuinely 1:1, or the duplicates agree. Worked example:
   [category tile sort order](../../toga2-commerce/features/category-tile-sort-order.md).
 
+### Grouped / aggregate queries (`group=` + an `_`-prefixed aggregate field)
+
+Each output row = one bucket: the group key(s) + the aggregate values.
+
+- **Stored ROOT column key** (`group=status`): selected as `Table.field AS field` in aggregate mode
+  only and copied into the row (`V2.php` ~L5236 map, ~L5468 select, ~L5739 copy). Before TRUE-82876
+  it went into `GROUP BY` but never into the SELECT, so buckets had counts and **no key** (UI showed
+  "NONE"). Flat (non-aggregate) queries are unchanged.
+- **The key is ACL-gated:** it is returned only if `resolveColumnReference([... 'isValueReturned'
+  => true])` passes, so a group column the caller cannot READ is never returned, in any
+  `identifier_acl_mode`.
+- **Computed `FIELD_SQL` and joined-path group fields** already return their key.
+- **Cross-client** `mergeGroupRows()` merges buckets by the key value — it needs the key present
+  (see [cross-client retrieval](cross-client-data-retrieval.md)).
+
+**Known gaps (open, not fixed — 2026-10-18):**
+- A **joined `Table.field`** group key is still not selected.
+- `FOUND_ROWS` / the total count is wrong for grouped queries — do not page a grouped result by it.
+- Grouped queries still add an `ORDER BY uuid` tie-breaker, which a strict `ONLY_FULL_GROUP_BY`
+  server rejects. Prod `sql_mode` is unverified; local MySQL accepts it (see
+  [local vs prod MySQL config](../../dbchanges2/workflows/local-vs-prod-mysql-config-parity.md)).
+
 ### ⚠ `depth` and `calcDepth` are IGNORED inside the base64 `_` options blob
 
 `fields`, `where`, `sort`, `join` work inside the `_` blob. **`depth` and `calcDepth` do not** —
@@ -368,7 +390,10 @@ where=(field:op:value,LOGIC,field:op:value,(nested,OR,nested))
 - **A dotted FK path (`case.uuid`) in `where` fails `EV-8` on a list GET.** Filter by a parent FK
   through a join alias: `ojoin=Cases:Cases.id=Tickets.caseId&where=(Cases.uuid:eq:<uuid>)` (or a
   `TableViewJoins` row that gives the alias). A path through an **inherent child**
-  (`ticketUsers.user.uuid`) does work.
+  (`ticketUsers.user.uuid`) does work — but only when the **first** segment is an inherent child
+  of the route (`buildChildPathWhereSql`). A path that starts with a forward FK hop fails
+  (`service-requests` → `ticket.ticketUsers.user.uuid`). No-api2-change fix: a TableView that
+  outer-joins the FK table and the bridge, then `where` on the join alias.
 
 ### ✅ You CAN `where` on a calculated (`FIELD_SQL`) field — but ONLY with the BARE name
 
@@ -625,6 +650,8 @@ If you need the behaviour, loop uuids client-side. Point 3 is the durable, non-o
   [V2 request logging](request-logging.md).
 
 ## Change history
+- 2026-10-18 — Grouped queries: stored root group key now selected + ACL-gated; known gaps (joined key, total count, `ORDER BY uuid` under ONLY_FULL_GROUP_BY) (TRUE-82876). (jcardinal)
+- 2026-10-17 — Child-path `where` must start at an inherent child; FK-first path → TableView join alias (TRUE-82872). (jcardinal)
 - 2026-10-17 — Multi-sort comma list + `uuid` tie-breaker for stable paging; sort on calc works; refreshed where-path line refs. (jcardinal)
 - 2026-10-17 — POST create = 201, PUT/DELETE = 200 (TRUE-82889). (jcardinal)
 - 2026-10-15 — Security: `where` on an unreadable field still filters under default `identifier_acl_mode=log` (hash guessing); dotted FK path in `where` = `EV-8`, use a join alias (TRUE-82836). Folded older history. (jcardinal)

package/package.json

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