toga-ai 1.0.1049 → 1.0.1050

package/knowledge/2.0/apps/_underscore/features/contact-customer-required-internal-customer.md

@@ -18,6 +18,8 @@ files:
   - worker2/Worker/Startech.php
   - toga25-supply/src/utils/internalCustomer.ts
   - toga2-commerce/src/utils/internalCustomer.ts
+  - toga2-commerce/src/api/CartApi.ts
+  - toga2-commerce/src/api/axiosInstance.ts
 related:
   - ./client-user-contactid-required.md
   - ../../api2/features/nested-relationship-writes.md
@@ -28,7 +30,10 @@ Every `Client_<Tenant>.Contacts` row must have a `customerId`; with no real cust
 
 ## Summary
 
-Decision (2026-10-16, jcardinal, TRUE-82841): `Contacts.customerId` is **NOT NULL** in every 2.0 client DB. Every tenant has ONE `Customers` row named `Internal` with the **same hardcoded uuid** `20436694-8925-4eea-95b9-c97d7caa813b`. Contacts with no real customer (client staff, imports) point at it.
+Decision (2026-10-16, jcardinal, TRUE-82841): `Contacts.customerId` is **NOT NULL** in every 2.0 client DB. Every tenant has ONE "Internal customer" `Customers` row with the **same hardcoded uuid** `20436694-8925-4eea-95b9-c97d7caa813b`. Contacts with no real customer (client staff, imports) point at it.
+
+- **The row is NAMED AFTER THE CLIENT, not "Internal"** (jcardinal). `Client/2026-10-16a` sets the name with a `CASE DATABASE()` map of client DB → client name (copied from prod `Core.Clients` at authoring time, e.g. `Client_Compass` → `'Compass Group'`); an unknown DB falls back to `SUBSTRING(DATABASE(), 8)`.
+- **Find it only by the uuid, never by name.**
 
 **Rule:** every code path that creates a Contact must set a customer.
 - api2 payload → `customer: {uuid: <INTERNAL_CUSTOMER_UUID>}` (or the real customer's uuid).
@@ -36,13 +41,16 @@ Decision (2026-10-16, jcardinal, TRUE-82841): `Contacts.customerId` is **NOT NUL
 
 Rejected: a `Customers.slug` marker column; app-level validation instead of a DB `NOT NULL`; a silent model-wide default.
 
-**Rollout order:** `Client/2026-10-16a` seed (before deploy) → code deploy → `Client/2026-10-16b` backfill + `NOT NULL` (after deploy). Running `b` before the code fix breaks every unfixed create path.
+**Rollout order:** `Client/2026-10-16a` seed **+ backfill** (before deploy) → code deploy → `Client/2026-10-16b` straggler backfill + `NOT NULL` (after deploy).
+- Backfill must run BEFORE the code that sends `customer`: api2 matches nested contacts on `customerId` too (gotcha below), so an un-backfilled NULL contact would be duplicated.
+- Running `b` before the code fix breaks every unfixed create path.
 
 ## How it works
 
 - Constant: `_Model_Client_Customer::INTERNAL_CUSTOMER_UUID` (`_underscore/Model/Client/Customer.php`). Front-ends keep their own `INTERNAL_CUSTOMER_UUID` in `src/utils/internalCustomer.ts` (toga25-supply, toga2-commerce).
 - `internalCustomerId(string $database = DB_CLIENT): int` — resolves the id by uuid on the given connection; ids differ per tenant, the uuid does not.
-- `Contacts.customerId` = `Core.RecordFields` id **1651** (record 37 `contacts`), childPolicy `MATCH` — so a `{uuid}` nested customer links, never creates. Base role can write it in Wje / Elite / Pcmaticb2b / Compass / CompassCanada; Public cannot.
+- `Contacts.customerId` = `Core.RecordFields` id **1651** (record 37 `contacts`), childPolicy `MATCH`, **`isIdentifier = 1`** (prod) — a `{uuid}` nested customer links, never creates (`customers.uuid` 675 is an identifier). Base role can write it in Wje / Elite / Pcmaticb2b / Compass / CompassCanada; Public cannot.
+- Nested-write ACL = top-level record create + FIELD write for every nested field sent; a missing 1651 grant is EV-12 (400), never a silent drop — see [nested-relationship-writes](../../api2/features/nested-relationship-writes.md).
 - A contact can also be created **through a parent's nested `contact` FK** — those paths need the customer too (list of contact FKs that can CREATE: [nested-relationship-writes](../../api2/features/nested-relationship-writes.md)).
 
 ### Every contact-creation path (2026-10-16)
@@ -58,15 +66,17 @@ Rejected: a `Customers.slug` marker column; app-level validation instead of a DB
 | Freshservice syncs (contacts + nested on units/tickets) | `worker2/Worker/Wje.php`, `Worker/Elite.php` | Wje, Elite | Internal uuid |
 | Startech tickets (nested contact) | `worker2/Worker/Startech.php` | Pcmaticb2b | Internal uuid — see gotcha |
 | Location contact | toga25-supply `useCreateLocationContact.ts` | all | Internal uuid |
-| Cart "Add user" nested contact | toga2-commerce `CartApi.ts` `addUser` | all | Internal uuid |
+| Cart "Add user" nested contact | toga2-commerce `CartApi.ts` `addUser` (signed-in user's token) | all | Internal uuid — see gotcha |
 | Rate SSO | `Model/Rate/ClientAuthentication.php` | Rate | already a real customer |
 
 ## Gotchas
 
-- **⚠ A `MATCH_UPSERT` nested contact that sends `customer` OVERWRITES an existing contact's customer.** Matching is link-and-update. Startech/Pcmaticb2b: 3 contacts with real customers carry `c_startechUserId` and can be flipped to Internal — **open item**.
+- **⚠ A nested contact that sends `customer` is MATCHED on `customerId` too** (1651 is an identifier). `{c_wjeUserId, customer:{uuid}}` searches c_wjeUserId AND customerId; an existing contact with NULL or a different customer does not match, so `MATCH_CREATE`/`MATCH_UPSERT` **creates a duplicate contact** (not an overwrite). Startech/Pcmaticb2b: 3 contacts with a real customer + `c_startechUserId` get a duplicate on their next Startech ticket — **open item**; proposed fix (look up by `c_startechUserId` first, send `{uuid}`) not taken.
+- **Commerce signup ACL (prod 2026-10-16):** `addUser` (`POST /users` depth -1) runs on the signed-in user's token (`src/api/axiosInstance.ts` ~L193), not the public token. Client_Compass: users-create roles = Base(1), API(3), Admin(4), SuperUser(5), Manager(8); 1651 writable for Base, API, Compass Base(7) only — Admin(4) alone would fail EV-12 (no current user depends on it; parity grant offered, not taken). Client_CompassCanada: only Base creates users, and Base can write 1651. Everyone who can sign up today still can.
 - **Prod baseline 2026-10-16:** ~443k contacts had `customerId` NULL; only Rate (726/728) and Pcmaticb2b (21/398) used the field; many clients had zero `Customers` rows. Most NULL contacts are client staff linked from `Users.contactId`.
 - New raw-SQL contact INSERTs: include `customerId` in the column list — omitted, the INSERT fails once the column is `NOT NULL`. Same write-order lesson as [client-user-contactid-required](./client-user-contactid-required.md).
 - Backfill/ALTER technique (`dtUpdated = dtUpdated`, strict-mode in-place ALTER): [rerunnable-additive-inserts](../../dbchanges2/features/rerunnable-additive-inserts.md).
 
 ## Change history
+- 2026-10-16 — Row named after the client (find by uuid only); backfill moved into `a` (before deploy) because 1651 is an identifier and unmatched contacts get duplicated, not overwritten; commerce signup ACL check (TRUE-82841). (jcardinal)
 - 2026-10-16 — Initial. Internal customer (fixed uuid, every tenant) + `Contacts.customerId` NOT NULL; every contact-create path fixed (TRUE-82841). (jcardinal)

package/knowledge/2.0/apps/api2/features/nested-relationship-writes.md

@@ -196,10 +196,13 @@ behaviour — it bites any write to a nested child, not one feature. Worked exam
 - **Declaring a `c_` field on the model does not make it searchable** — the `CustomRecordFields.isIdentifier` flag is the gate; set the flag, not the child policy.
 - **An identifier that is unique only inside a parent (e.g. `bundles.number` per catalog) links the WRONG record, silently.** The match uses only the identifier fields sent, so `bundle: {number: "001"}` hits another catalog's `001`. Send `uuid` (or add the scoping identifier) resolved in the caller. Seen on Prudential India REQs — see [bundle catalog resolution](../../../clients/prudential/features/service-request-bundle-catalog-resolution.md).
 - **⚠ A nested `unit` with only an `item` (no serial/asset tag) REUSES one existing unit.** `ServiceRequests_Units.unitId` is `MATCH_UPSERT` and `Units.itemId` is an identifier, so `{unit:{item:{uuid}}}` matches the first unit of that item — every SR links the same unit. For serial-less requests attach a **bundle** instead (`ServiceRequests_Bundles.bundleId` is `MATCH`; send `{bundle:{uuid}}`). See [Adyen reclaim flow](../../../clients/adyen/features/service-request-salesorder-netsuite.md).
-- **Parent FKs that can CREATE a Contact** (prod `Core.RecordFields.childPolicy`, 2026-10-16): `MATCH_CREATE` — `Users.contactId`, `PurchaseOrders.contactId`; `MATCH_UPSERT` — `Tickets.contactId`, `Tickets.reportedByContactId`, `Units.contactId`, `UnitNotes.contactId`, `Entitlements.contactId`, `ServiceRequests.requestedForContactId`, `ContactPhoneNumbers.contactId`. A nested contact created through any of these must carry a `customer` — see [contact-customer-required-internal-customer](../../_underscore/features/contact-customer-required-internal-customer.md). On `MATCH_UPSERT`, a `customer` sent for a matched contact overwrites its existing customer.
+- **Parent FKs that can CREATE a Contact** (prod `Core.RecordFields.childPolicy`, 2026-10-16): `MATCH_CREATE` — `Users.contactId`, `PurchaseOrders.contactId`; `MATCH_UPSERT` — `Tickets.contactId`, `Tickets.reportedByContactId`, `Units.contactId`, `UnitNotes.contactId`, `Entitlements.contactId`, `ServiceRequests.requestedForContactId`, `ContactPhoneNumbers.contactId`. A nested contact created through any of these must carry a `customer` — see [contact-customer-required-internal-customer](../../_underscore/features/contact-customer-required-internal-customer.md).
+- **⚠ Every identifier field SENT joins the match.** `contacts.customerId` (1651) is `isIdentifier = 1`, so `{c_wjeUserId, customer:{uuid}}` matches on c_wjeUserId AND customerId. A contact with a NULL/different customer does not match → `MATCH_CREATE`/`MATCH_UPSERT` **creates a duplicate**. Backfill the field before code starts sending it.
+- **Nested-write ACL** (`V2.php` `getForeignKeyValue` ~L9790-10469): no record-level ACL on the nested record. Checked = top-level record create (e.g. users, Core.Records 2) + FIELD write for every field sent on the nested record (e.g. contacts, 37), using the caller's `id.client.roles`. A missing field grant fails **EV-12** (400, "lack write permissions"), never a silent drop.
 - **Singular-FK back-reference defects:** UPDATE path drops the parent's forward FK (echoes `null`); CREATE path re-parents a value-matched child to the newest writer (stolen child row). One defect, two symptoms.
 
 ## Change history
+- 2026-10-16 — Corrected: a sent identifier field (contacts.customerId 1651) joins the match, so a mismatched contact is duplicated, not overwritten; nested-write ACL = top-level create + per-field write, EV-12 on a gap (TRUE-82841). (jcardinal)
 - 2026-10-16 — Listed the parent FKs whose nested contact can CREATE a Contact (each must send `customer`); MATCH_UPSERT overwrites a matched contact's customer (TRUE-82841). (jcardinal)
 - 2026-09-30 — Gotcha: item-only nested unit matches an existing unit; use a bundle for serial-less SRs. (rgirish)
 - 2026-09-29 — Gotcha: a per-parent identifier (`bundles.number`) matches across parents and links the wrong row. (rgirish)

package/knowledge/2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md

@@ -326,6 +326,10 @@ PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
   NULL (no silent `0`), and in-place NOT NULL **needs** strict mode (error 1846 otherwise, even with
   0 NULLs). Backfill with `dtUpdated = dtUpdated` so syncs do not see every row as changed. Worked
   file: `Client/2026-10-16b - TRUE-82841 Contacts customerId NOT NULL.sql`.
+- **Backfill BEFORE the deploy when the column is an api2 identifier.** Put the main backfill in the
+  pre-deploy seed file, and repeat it for stragglers in the post-deploy ALTER file. Otherwise new code
+  that sends the field fails to match un-backfilled rows and api2 creates duplicates (TRUE-82841:
+  `Client/2026-10-16a` seed + backfill, `Client/2026-10-16b` straggler backfill + ALTER).
 
 ### ⚠ A column DEFAULT does NOT protect a `_Model`-written column
 
@@ -555,6 +559,7 @@ an INSERT that names only `uuid`/`tableViewId`/`recordFieldId`/`isVisible`/`inde
   [FIELD_SQL calculated fields](../../_underscore/features/calculated-sql-fields.md).
 
 ## Change history
+- 2026-10-16 — Backfill an api2-identifier column before the deploy (seed file), stragglers + ALTER after (TRUE-82841). (jcardinal)
 - 2026-10-16 — NOT NULL alternative for big tables: strict session + `ALGORITHM=INPLACE, LOCK=NONE`
   (1846 without strict), `lock_wait_timeout`, `dtUpdated = dtUpdated` backfill (TRUE-82841). (jcardinal)
 - 2026-10-16 — Fan-out seed keyed on a slug another folder sets can silently no-op; back-fill slugs

package/knowledge/2.0/apps/worker2/features/startech-webhook-handler.md

@@ -62,9 +62,10 @@ Both filters use `fields` to request only `id`/`uuid`. Filtering on `ticketTypeI
 
 - `c_escalateToStartech: 0` must be in the payload. If omitted, the interceptor still skips Startech (null is also falsy), but the field stays NULL in TOGA 2.0 — making webhook tickets indistinguishable from TOGaDesk-created ones.
 - `ticketType` is resolved via `c_startechTicketTypeId` on `TicketTypes` — not a hardcoded string. Startech type IDs: SR=6, PCS=54, API=201.
-- **⚠ The nested `contact` sends the Internal customer** (`Contacts.customerId` NOT NULL — see [contact-customer-required-internal-customer](../../_underscore/features/contact-customer-required-internal-customer.md)). `Tickets.contactId` is `MATCH_UPSERT`, so a matched existing contact gets its customer overwritten to Internal. Open item (2026-10-16): 3 Pcmaticb2b contacts with real customers carry `c_startechUserId` and are exposed.
+- **⚠ The nested `contact` sends the Internal customer** (`Contacts.customerId` NOT NULL — see [contact-customer-required-internal-customer](../../_underscore/features/contact-customer-required-internal-customer.md)). `Tickets.contactId` is `MATCH_UPSERT` and `customerId` is an identifier, so the match uses `c_startechUserId` AND customerId. A contact whose customer is not the Internal one does not match and **gets a DUPLICATE contact** (not an overwrite). Open item (2026-10-16): 3 Pcmaticb2b contacts with a real customer + `c_startechUserId` will be duplicated on their next ticket. Proposed fix, not taken: look up the contact by `c_startechUserId` first and send `{uuid}`.
 
 ## Change history
+- 2026-10-16 — Corrected: a mismatched-customer contact is duplicated, not overwritten; proposed lookup-first fix recorded (TRUE-82841). (jcardinal)
 - 2026-10-16 — Nested contact now carries the Internal customer; noted the customer-overwrite risk on matched contacts (TRUE-82841). (jcardinal)
 
 ## Related

package/package.json

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