toga-ai 1.0.1072 → 1.0.1073

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/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/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** —
@@ -628,6 +650,7 @@ 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.1072",
+  "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",