toga-ai 1.0.1067 → 1.0.1069

package/knowledge/2.0/apps/_underscore/INDEX.md

@@ -22,8 +22,9 @@
 | [_Component_*/_Model_* project-namespace registration (autoloader) & backslash-qualify traps](features/component-model-namespace-registration.md) | Project-local `_Component_*`/`_Model_*` must declare the app namespace AND live in a `<Name>/<Name>.php` directory, or the autoloader fatals at runtime; open wh |
 | [_Config group access — the two-argument "optional" form does NOT rescue a missing GROUP](features/config-group-access.md) | `_Config::<group>('prop', false)` does NOT rescue a MISSING GROUP (only a missing prop) — guard with `_Config::isGroupSet()`; open before reading per-environmen |
 | [Contacts require a customerId — the Internal customer & every contact-creation path](features/contact-customer-required-internal-customer.md) | Every `Client_<Tenant>.Contacts` row must have a `customerId`; with no real customer, use the shared Internal customer (fixed uuid in every tenant). |
+| [Contact related records — notes, files, contact types (slug), delete](features/contact-notes-files-types.md) | Shared Client-DB data model around a Contact (notes, files, typed contact types, delete); open before linking anything to a contact, keying on a contact type, o |
 | [Core.Domains — the app host registry (and why you cannot derive a host)](features/core-domains-app-host-registry.md) | `Core.Domains` is the authoritative host↔client↔app↔env registry; a host is NOT derivable from env slug or api host — read the table. |
-| [Customer related records — primary location, Locations_Customers, files, notes](features/customer-locations-files-notes.md) | Shared Client-DB data model around a Customer (locations, files, notes, contact count); open before linking anything to a customer or listing a customer's locat |
+| [Customer data model — tiers, industries, customer since, locations, files, notes](features/customer-locations-files-notes.md) | Shared Client-DB data model around a Customer (tier, industry, customer-since, site/contact counts, locations, files, notes); open before adding a customer fiel |
 | [Re-pointing a DB alias mid-request (_Database::register park/restore)](features/database-alias-repointing.md) | `_Database` keys **all live per-database runtime state by the connection ALIAS** (`Client` / `_underscore::DB_CLIENT`, `ClientLogs`, `Archive`), **not** by the |
 | [Effective persona resolution (_Model_Client_User::_personaIds) — the three sources and the sector hop](features/effective-persona-resolution.md) | A user's EFFECTIVE persona set = UNION of three sources (`Users_Personas` + own-location + 5-hop sector `Locations_Personas`), owned by `_personaIds()`; open be |
 | [2.0 Email Send Pipeline (queue + Send worker)](features/email-send-pipeline.md) | In 2.0, `_Email::send()` **does not transmit** — it queues the message. |

package/knowledge/2.0/apps/_underscore/architecture.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: architecture
 status: active
-updated: 2026-10-13
+updated: 2026-10-17
 owners: ["jcardinal", "rgirish", "mhammontree", "ajean"]
 files:
   - _underscore/_underscore.php
@@ -436,7 +436,16 @@ multi-file UI components (`.php`/`.html`/`.css`/`.js`) invoked as `<_ComponentNa
   message/trace to the client if `display_errors` is on unconditionally. Confirm `display_errors` is
   disabled in production and that the framework's error surface returns a sanitized envelope (not a raw
   stack trace) to API consumers. Not yet done — tracked as a follow-up.
+- **`class_exists('X')` throws, not false, for an unknown class.** It runs the `_Loader` autoloader,
+  which throws on a missing file → 500 EO-1. For optional PHP-extension classes (e.g. `Transliterator`,
+  intl is missing on local XAMPP) call `class_exists('\X', false)`. Live case:
+  `_Model_Client_CustomerLookup::deriveSlug()` (TRUE-82903).
+- **A NOT NULL column's DB default never applies to a model INSERT.** `_Model` writes every declared
+  field explicitly, so a `FIELD_INTEGER` with no `FIELDOPT_DEFAULT` inserts NULL → MySQL 1048 on a
+  `NOT NULL DEFAULT 0` column. Declare `FIELDOPT_DEFAULT` on the model to match every NOT NULL column
+  default. Live cases: `CustomerTier` / `Industry.sortOrder` (TRUE-82903), `Cache Tables.safeRecordCount`.
 
 ## Change history
 
 - 2026-10-07 — Corrected tenant DB-name resolution: resolve `Core.Clients` id columns into `Core.Databases`; `clientIdentifier` is not the suffix (Compass). (mhammontree)
+- 2026-10-17 — Gotchas: `class_exists` autoload throws; model INSERT ignores DB column defaults (TRUE-82903). (jcardinal)

package/knowledge/2.0/apps/_underscore/features/calculated-sql-fields.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-17
+updated: 2026-10-17
 owners: [snaredla, jcardinal, bala, apeterson, rgirish]
 files:
   - _underscore/Model.php
@@ -289,8 +289,13 @@ Keep the expression cheap, or expect callers to pay for it on every list.
   same-parent child inserts then deadlock (MySQL 1213). This is exactly how `PurchaseOrder._total`
   deadlocked the ASN path; see
   [save-cascade stored-field deadlocks](./model-save-parent-cascade-stored-field-deadlock.md).
+- **Count calc fields are for listing columns only — not detail-tab counts.** A calc field skips the
+  child's row-ACL filters and cannot count across the Core vs Client cluster split. A detail tab's count
+  = the embedded tab table's own list total (`fields=uuid`, page size 1, `meta.totalRecordCount`). Full
+  rule: toga25-desk `docs/decisions/0153-*`, PLATFORM rule 37.
 
 ## Change history
+- 2026-10-17 — Count calc fields: listing columns only; detail-tab counts use the list total (TRUE-82903). (jcardinal)
 - 2026-09-17 — Recorded a live instance of the `self::` trap: `_Model_Client_Item`'s four composite
   fields (`_qtyOnHand`, `_qtyAvailable`, `_qtyBackordered`, `_qtyOnOrder`) used **`self::`**, so a
   client subclass overriding a *leaf* `_qty*` method was silently ignored unless it re-declared all

package/knowledge/2.0/apps/_underscore/features/contact-notes-files-types.md

@@ -0,0 +1,70 @@
+---
+title: Contact related records — notes, files, contact types (slug), delete
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-10-17
+owners: [jcardinal]
+files:
+  - _underscore/Model/Client/Contact.php
+  - _underscore/Model/Client/ContactNote.php
+  - _underscore/Model/Client/Contacts/File.php
+  - _underscore/Model/Client/ContactType.php
+  - dbchanges2/Client/2026-10-17c - ContactsTypesFilesNotes.sql
+  - dbchanges2/Core/2026-10-17e - TRUE-82871 ContactsHiFiCore.sql
+  - dbchanges2/Core/2026-10-17f - TRUE-82871 ContactDeleteInterceptor.sql
+related:
+  - ./customer-locations-files-notes.md
+  - ./record-hard-delete.md
+  - ./record-activity-timeline.md
+  - ./note-record-authorship.md
+  - ./contact-customer-required-internal-customer.md
+  - ../../toga25-blox/features/contact-channels-save.md
+---
+Shared Client-DB data model around a Contact (notes, files, typed contact types, delete); open before linking anything to a contact, keying on a contact type, or deleting a contact.
+
+## Summary
+
+Added 2026-10-17 (TRUE-82871, built for TOGa Desk, usable by any app). Copies the Customer notes/files pattern
+([customer related records](./customer-locations-files-notes.md)) — read that doc for the shared shape.
+
+| Piece | Shape | Core ids |
+|---|---|---|
+| `ContactTypes.slug` | `VARCHAR(64)` unique; seeded `primary`, `technical`, `billing`, `executive` in every client DB | RecordFields 2815 (Records 169) |
+| `Contacts_Files` | copy of `Customers_Files` | Records 385 `contact-files`, RecordFields 2816-2819 |
+| `ContactNotes` | copy of `CustomerNotes`: write-once, server-stamped `authorUserId` | Records 386 `contact-notes`, RecordFields 2820-2825 |
+| Delete | PRE DELETE interceptor on Records 37 | `Core/2026-10-17f` |
+
+## How it works
+
+- **Contact types:** presets, filters, and code key on `slug`, never `name` (names are display copy). Badge color
+  comes from the Surface vocabulary `contact-type` (term value = slug) + neutral ThemeTokens — no color column.
+  An existing row named Primary/Technical/Billing/Executive got the slug instead of a duplicate row.
+- **Inherent children:** `contacts → contact-files` (`contactFiles[]`), `contacts → contact-notes` (`contactNotes[]`),
+  both isParentTouched 1.
+- **ContactNotes author:** `authorUserId` from `_Model::getRequestUserId()` in `save()`; no client user (API key,
+  worker) → 400; updates refused. See [note authorship](./note-record-authorship.md).
+- **Client ACL:** granted to every role with a global read on contacts. 169: read (slug read-only). 385: CRUD.
+  386: create + read, only `note` writable.
+- **Activity:** root `contacts` → surface `contact-activity`; `contact-notes` in `CREATE_HIDDEN_ROUTES`
+  ([record activity timeline](./record-activity-timeline.md)).
+- **Delete:** block / detach / cascade map in `Contact::relatedRows()` — full list in
+  [record hard delete](./record-hard-delete.md) (Contact rule). A blocked delete returns a 400 naming what links it.
+- **Saving primary email/phone from a form:** blox `updateContactChannels` (see
+  [contact channels save](../../toga25-blox/features/contact-channels-save.md)).
+
+## Gotchas
+
+- **Run order is Client first:** `Client/2026-10-17c` on every client DB → deploy `_underscore` → `Core/2026-10-17e`
+  and `f` (the Client file reads nothing from Core; Core rows point at models/tables that must already exist).
+- **New `fileId` FK table → `FILE_REFERENCE_TABLES`.** `Contacts_Files` was added; without it a customer/case purge
+  could delete a Files row a contact still uses.
+- **Client schemas drift** (e.g. `Client_True.TransferOrders` has no `contactId`) — the delete map probes optional
+  columns with `columnExists()`.
+- **TableViewPresets are per-user** (`userId` NOT NULL) — "default preset views" from a design cannot be seeded.
+
+## Change history
+- 2026-10-17 — Created: ContactTypes.slug + seeds, Contacts_Files, ContactNotes, contact activity root, contact delete (TRUE-82871). (jcardinal)

package/knowledge/2.0/apps/_underscore/features/customer-locations-files-notes.md

@@ -1,5 +1,5 @@
 ---
-title: Customer related records — primary location, Locations_Customers, files, notes
+title: Customer data model — tiers, industries, customer since, locations, files, notes
 framework: "2.0"
 repo: _underscore
 project: _Underscore
@@ -10,39 +10,59 @@ updated: 2026-10-17
 owners: [jcardinal]
 files:
   - _underscore/Model/Client/Customer.php
+  - _underscore/Model/Client/CustomerLookup.php
+  - _underscore/Model/Client/CustomerTier.php
+  - _underscore/Model/Client/Industry.php
   - _underscore/Model/Client/Locations/Customer.php
   - _underscore/Model/Client/Customers/File.php
   - _underscore/Model/Client/CustomerNote.php
-  - dbchanges2/Core/2026-10-17b - CustomerLocationsFilesNotesActivity.sql
+  - dbchanges2/Client/2026-10-17e - TRUE-82903 CustomerTiersIndustries.sql
+  - dbchanges2/Core/2026-10-17h - TRUE-82903 CustomerTiersIndustries.sql
   - dbchanges2/Client/2026-10-17b - CustomerLocationsFilesNotes.sql
-  - dbchanges2/Core/2026-10-17d - CustomerNotesRecordFieldNames.sql
+  - dbchanges2/Core/2026-10-17b - CustomerLocationsFilesNotesActivity.sql
 related:
   - ./record-hard-delete.md
   - ./record-activity-timeline.md
   - ./note-record-authorship.md
   - ./tableview-joins.md
+  - ./calculated-sql-fields.md
   - ./model-save-parent-cascade-stored-field-deadlock.md
   - ./contact-customer-required-internal-customer.md
   - ./acl-permission-chain.md
+  - ../../api2/features/api-payload-interceptors.md
 ---
-Shared Client-DB data model around a Customer (locations, files, notes, contact count); open before linking anything to a customer or listing a customer's locations.
+Shared Client-DB data model around a Customer (tier, industry, customer-since, site/contact counts, locations, files, notes); open before adding a customer field, a customer lookup, or linking anything to a customer.
 
 ## Summary
 
-Added 2026-10-17 (TRUE-82870, built for TOGa Desk, usable by any app). All tables live in every `Client_*` DB.
+Built for TOGa Desk (TRUE-82870, TRUE-82903), usable by any app. All tables live in every `Client_*` DB.
 
 | Piece | Shape | Core ids |
 |---|---|---|
 | `Customers.primaryLocationId` | FK → Locations, standard field | RecordFields 2799 |
 | `Customers._contactCount` | non-stored `FIELD_SQL` COUNT of Contacts by `customerId` | RecordFields 2800 |
+| `Customers.customerTierId` | nullable FK → CustomerTiers | RecordFields 2826-2841 (with below) |
+| `Customers.industryId` | nullable FK → Industries | |
+| `Customers.dateCustomerSince` | `DATE` | |
+| `Customers._siteCount` | non-stored `FIELD_SQL` COUNT of `Locations_Customers` rows | |
+| `CustomerTiers` | lookup (name, slug, sortOrder, isActive) | Records 387 `customer-tiers` |
+| `Industries` | lookup, same shape | Records 388 `industries` |
 | `Locations_Customers` | many-to-many bridge, `UNIQUE (locationId, customerId)` | Records 382 `location-customers` |
 | `Customers_Files` | copy of `Cases_Files`, `UNIQUE (customerId, fileId)` | Records 383 `customer-files` |
 | `CustomerNotes` | copy of `CaseNotes` minus stage: write-once, internal | Records 384 `customer-notes` |
 
-RecordFields 2801-2814 cover the three new records.
+RecordFields 2801-2814 cover 382-384. SQL: `Client/2026-10-17e` + `Core/2026-10-17h` (tiers/industries), `Client/2026-10-17b` + `Core/2026-10-17b` (locations/files/notes).
 
 ## How it works
 
+- **Customer lookups (`CustomerTiers`, `Industries`)** extend abstract `_Model_Client_CustomerLookup`. Its PRE
+  POST/PUT/PATCH/DELETE api2 interceptors: trim `name`; derive `slug` from `name`; duplicate slug → readable 400;
+  `sortOrder` = MAX+1 when not sent; delete blocked while any customer points at the row. A new customer lookup =
+  subclass + `customerColumn()` + `deleteBlockedMessage()`. Subclasses declare `FIELDOPT_DEFAULT` for every
+  NOT NULL column (`sortOrder` 0, `isActive` true) — the model writes NULL otherwise.
+- **Tier colours are data, not code:** Surface vocabulary `customer-tier` (kind TYPE) + client ThemeTokens
+  `color.tier.<slug>`.
+- **"Customer since" = `dateCustomerSince`.** Never use `dtCreated` for it (that is the row's insert time).
 - **Location of a customer:** use `primaryLocationId` (a real join). `_location` (city, state from the bill-to
   Address) is kept for its existing readers — do not build new features on it.
 - **Bridge, not `Locations.customerId`:** a location may belong to many customers (developer decision).
@@ -61,15 +81,19 @@ RecordFields 2801-2814 cover the three new records.
 
 ## Gotchas
 
+- **`deriveSlug()` checks `Transliterator` with `class_exists('\X', false)`** — rule lives in
+  [_underscore architecture § Gotchas](../architecture.md#gotchas).
 - **Never OUTER-join a many-to-many bridge into a shared TableView.** blox sends every join of a view on every
   request (`buildJoinOptions`), so the general listing repeats each row once per bridge match. Make a
   separate parent-scoped view instead (rule lives in [tableview-joins](./tableview-joins.md)).
-- **`_contactCount` must stay non-stored** — a stored self-aggregate deadlocks the save cascade
-  ([details](./model-save-parent-cascade-stored-field-deadlock.md)).
+- **`_contactCount` / `_siteCount` must stay non-stored** — a stored self-aggregate deadlocks the save cascade
+  ([details](./model-save-parent-cascade-stored-field-deadlock.md)). They are for listing columns; detail-tab
+  counts come from the tab table's own list total (see [calculated fields](./calculated-sql-fields.md)).
 - **Assets link to a customer through Contacts** (`Units.contactId → Contacts.customerId`), not directly.
 - **Copied RecordFields need `name`.** `CaseNotes` RecordFields 2743-2749 have NULL `name` (not fixed), so the
   copy 2809-2814 came out NULL too; filled by `Core/2026-10-17d`. Set `name` on every new RecordField.
 
 ## Change history
+- 2026-10-17 — Added CustomerTiers (387), Industries (388), `_Model_Client_CustomerLookup` interceptors, `customerTierId`, `industryId`, `dateCustomerSince`, `_siteCount` (TRUE-82903). (jcardinal)
 - 2026-10-17 — Filled NULL `name` on RecordFields 2809-2814 (Core/2026-10-17d). (jcardinal)
 - 2026-10-17 — Created: primaryLocationId, _contactCount, Locations_Customers, Customers_Files, CustomerNotes (TRUE-82870). (jcardinal)

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-10-15
+updated: 2026-10-17
 owners: [apeterson, jcardinal]
 files:
   - _underscore/Model/Client/SalesOrderNote.php
@@ -63,10 +63,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) and `CustomerNotes` (2026-10-17) have a real author:** `authorUserId` stamped in `::save()` from `_Model::getRequestUserId()`. Copy that pattern for the real fix. See [Case status + stage gate](./case-status-and-stage-gate.md), [Customer related records](./customer-locations-files-notes.md).
+- **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).
 - **`dtStamp` is `FIELD_DATETIME_CREATED`** — stamped by the ORM on insert, the only provenance a note actually carries.
 
 ## Change history
+- 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,7 @@ 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`. Any other route → 400. **A new root = one map entry + its Surface
+  `service-request-activity`, `customers` → `customer-activity`, `contacts` → `contact-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 +45,7 @@ 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`) are dropped — the host screen merges the notes feed.
+  `case-notes`, `service-request-notes`, `customer-notes`, `contact-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`.
@@ -69,6 +69,7 @@ client `AclRecordScripts`. Data source: [record change audit log](record-change-
   (schema + api2 change) — not built.
 
 ## Change history
+- 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)
 - 2026-10-15 — Added roots `units`, `cases`, `service-requests` + their note routes to `CREATE_HIDDEN_ROUTES` (TRUE-82836). (jcardinal)

package/knowledge/2.0/apps/_underscore/features/record-hard-delete.md

@@ -11,6 +11,7 @@ owners: [jcardinal]
 files:
   - _underscore/Component/RecordDelete/RecordDelete.php
   - _underscore/Model/Client/Customer.php
+  - _underscore/Model/Client/Contact.php
   - _underscore/Model/Client/Ticket.php
   - _underscore/Model/Client/Case.php
   - _underscore/Model/Client/ServiceRequest.php
@@ -26,7 +27,7 @@ Map-driven hard delete of everything hanging off one record (block / detach / de
 `DELETE /v2/<route>/{uuid}` on an opted-in record runs a PRE DELETE interceptor that calls
 `_Component_RecordDelete::purge(['model' => static::class, 'id' => $id])`. `purge()` cleans the related
 rows from a map the model declares in `relatedRows()`; api2 then deletes the record row itself. Used by
-Tickets, Cases, ServiceRequests, Customers. The class DocBlock is the full contract — read it before editing.
+Tickets, Cases, ServiceRequests, Customers, Contacts. The class DocBlock is the full contract — read it before editing.
 
 ## How it works
 
@@ -44,9 +45,22 @@ Tickets, Cases, ServiceRequests, Customers. The class DocBlock is the full contr
 - **Customer rule (Records 113, 2026-10-17):** block on Contacts / SalesOrders / PurchaseOrders; detach Tickets /
   ServiceRequests / Cases `customerId`; delete Customers_Catalogs, Customers_Subscriptions, Locations_Customers,
   Customers_Files, CustomerNotes rows; orphan Files from Customers_Files.
+- **Contact rule (Records 37, interceptor `Core/2026-10-17f`):** block on Users, Tickets (`contactId`,
+  `reportedByContactId`, `assignedToContactId`, and `contactPhoneNumberId` via the contact's phone rows),
+  Tickets_Contacts, ServiceRequests.requestedForContactId, Units, SalesOrders (`contactId`, `requestedByContactId`),
+  PurchaseOrders, Entitlements, TransferOrders.contactId (optional). Detach the `contactId` author column of every
+  `*Notes` table (TransferOrderNotes optional) and Files.contactId (optional). Delete Contacts_Files (+ orphan Files),
+  ContactNotes, ContactAttempts, ContactMessagingOptIns, Campaigns_Contacts, Campaigns_MeetWithContacts,
+  Contacts_Tags, Contacts_Vendors, Contacts_Locations, Locations_Contacts, ContactAddresses / EmailAddresses /
+  PhoneNumbers. `preDelete` clears the contact's `primary*` pointers first (they and the children point at each other).
 
 ## Gotchas
 
+- **Client schemas differ — probe optional tables/columns.** A map entry for a table or column missing in one
+  `Client_*` DB fails that client's delete. Contact checks with `columnExists()` (`SHOW TABLES` / `SHOW COLUMNS`,
+  read host off) before adding TransferOrders / TransferOrderNotes / Files `contactId` entries — e.g.
+  `Client_True` has TransferOrders without `contactId`. Do the same for any table not in every client DB.
+
 - **New table with a `fileId` FK → add it to `FILE_REFERENCE_TABLES`.** Missing it makes the Files DELETE fail on
   the FK and roll back every delete that touches a shared file (loud, not silent).
 - **Client override of `relatedRows()` must merge `parent::relatedRows()` key by key;** a client `preDelete`
@@ -57,4 +71,5 @@ Tickets, Cases, ServiceRequests, Customers. The class DocBlock is the full contr
   losing the link would lose meaning (orders, required FKs like `Contacts.customerId`).
 
 ## Change history
+- 2026-10-17 — Contacts opted in (block / detach / cascade map, schema-drift probes); Contacts_Files added to FILE_REFERENCE_TABLES (TRUE-82871). (jcardinal)
 - 2026-10-17 — Created; Customers opted in, Customers_Files added to FILE_REFERENCE_TABLES (TRUE-82870). (jcardinal)

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

@@ -116,7 +116,7 @@ Page 1 of 25 still fetches exactly 25; page 254 fetches 500 per pass — ~13 rou
 - **MySQL `GET_LOCK` names cap at 64 chars and ERROR rather than truncate.** The original lock name was 80 chars.
 - **`_Query::fetchRows()` returns OBJECTS**, not arrays. CrossClient read them with array syntax throughout.
 - **A V2 LIST nests records under the route key** (`data: {"salesOrders": [...]}`); `parseClientResponse` required `data` to be a flat array and discarded every successful sub-response as unusable.
-- **`_Model` writes every declared field explicitly, so column defaults never apply.** `Tables.safeRecordCount` is NOT NULL and `buildCache` never assigned it. Likewise a Core column (`Records.ttlCache`) that exists in SQL but is not declared on the model makes `__get` throw.
+- **`Tables.safeRecordCount` must be assigned in `buildCache`** — model INSERTs ignore DB column defaults (rule lives in [_underscore architecture § Gotchas](../../_underscore/architecture.md#gotchas)). Likewise a Core column (`Records.ttlCache`) that exists in SQL but is not declared on the model makes `__get` throw.
 - **Dangling foreign keys used to fail an entire listing.** `getFullModelData()` threw out of `_Model::initialize()` when a referenced row did not exist; one orphaned pointer killed the whole page. It now logs and expands the relationship to `null`. **This affects every REST listing/GET in api2, not just cross-client.**
 - **`empty()`/`isset()` on a `_Model` field is unreliable** and fails in the "looks unauthenticated" direction — see [_Model magic-field access](../../_underscore/features/model-magic-field-access.md).
 - **Switching the `Client` DB alias mid-request** needs the park/restore path — `_Database` keys live connection state by **alias**, not physical schema. See [Re-pointing a DB alias mid-request](../../_underscore/features/database-alias-repointing.md).
@@ -128,6 +128,10 @@ Page 1 of 25 still fetches exactly 25; page 254 fetches 500 per pass — ~13 rou
   requests must add `$api->cacheInvalidations['<recordId>:<clientId>'] = ['recordId' => …,
   'clientId' => …]` for each record type it touched, or cross-client listings serve stale rows.
   Example: `_Model_Client_CaseRecordRemoval` (TRUE-82889).
+- **⚠ Fetch scope is either/or: `client=` scatter OR one tenant's own token — never both.** Sending
+  `client=` on another tenant's token makes `resolveScope()` fan out to THAT tenant's `Users_Clients`
+  (cross-tenant read). Seeded uuids also repeat across `Client_*` DBs, so multi-client UI rows must be
+  keyed by client uuid + record uuid. Full rule: toga25-desk ADR 0154, `GOTCHAS.md`.
 - **`curl_multi` busy-spin guard** — both multi loops `usleep(100)` when `curl_multi_select() === -1`.
 - **Known limitation — deep page-number paging is inherently O(page).** Serving page 4430 means materializing all 110,747 preceding rows into the cache. Adaptive chunking makes that cheaper, not cheap: cost still grows with depth, because a page **number** cannot be resolved without knowing everything before it. The durable answer is **exposing keyset cursors to the caller** so cost is independent of depth — the mechanism already exists (V2 supports `seekValues` + `seekUuid` correctly). Raised with the developer 2026-07-28 and **deliberately left unbuilt / not yet scoped**: a known limitation and candidate direction, not pending work.
 
@@ -141,4 +145,5 @@ 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 — 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/toga25-blox/INDEX.md

@@ -3,6 +3,7 @@
 | Doc | Summary |
 |-----|---------|
 | [TOGa Blox 2.5 — Architecture](architecture.md) | Shared React+TS SOURCE library for the new platform apps (new platform apps first; replaces toga-blox for all apps over time); read the ADR for full detail, not |
+| [Contact primary email/phone save (updateContactChannels) — table calls only](features/contact-channels-save.md) | How a contact edit form saves the contact's primary email and phone without nested writes; use it (do not rebuild it) in any app that edits a contact's email/ph |
 | [Old blox (toga-blox) straight port inside toga25-blox](features/old-blox-port.md) | Old `@agilant/toga-blox` code copied unchanged into toga25-blox (blox-v1 layer); open before touching any old component, its checks/config, or merging Storybook |
 | [GitHub Actions → AWS role via OIDC (trust policy + sub claim)](workflows/github-actions-aws-oidc-role.md) | How a GitHub Actions job assumes an AWS IAM role with OIDC, and the `sub` claim trap; open before creating or debugging any GitHub-to-AWS role ("Not authorized |
 | [Moving an old app from @agilant/toga-blox onto toga25-blox](workflows/moving-an-old-app-onto-toga25-blox.md) | Planned steps to switch an old app off the `@agilant/toga-blox` npm package onto toga25-blox source with zero import edits; open before moving any old app. |

package/knowledge/2.0/apps/toga25-blox/features/contact-channels-save.md

@@ -0,0 +1,45 @@
+---
+title: Contact primary email/phone save (updateContactChannels) — table calls only
+framework: "2.0"
+repo: toga25-blox
+project: TOGa Blox 2.5
+client: shared
+type: feature
+status: active
+updated: 2026-10-17
+owners: [jcardinal]
+files:
+  - toga25-blox/src/forms/contact/updateContactChannels.ts
+  - toga25-blox/src/forms/contact/updateContactChannels.test.ts
+related:
+  - ../../api2/features/nested-relationship-writes.md
+  - ../../_underscore/features/contact-notes-files-types.md
+  - ../../_underscore/features/contact-customer-required-internal-customer.md
+---
+How a contact edit form saves the contact's primary email and phone without nested writes; use it (do not rebuild it) in any app that edits a contact's email/phone.
+
+## Summary
+
+`updateContactChannels({registry, clientUuid, contactUuid, email?, phone?, signal?})` (exported from `forms`) saves
+the primary `contact-email-addresses` / `contact-phone-numbers` child rows with plain table calls, as the contact's
+own client. A channel left out is not touched.
+
+## How it works
+
+Per channel, comparing the value when the form opened (`current`) to the form value (`next`):
+1. **Changed, has a primary** → `PUT` the primary child row's value.
+2. **Set, no primary yet** → `POST` a child row, then `PUT` the contact's `primaryContactEmailAddress` /
+   `primaryContactPhoneNumber` = `{uuid}` of the new row.
+3. **Cleared** → `PUT` the contact's primary link to `null`. The child row is never deleted.
+
+## Gotchas
+
+- **Never save email/phone as nested children in one contact `PUT`.** Nested channel objects match by address text
+  tenant-wide — they can grab another contact's row or create duplicates
+  ([nested-relationship writes](../../api2/features/nested-relationship-writes.md)).
+- **No api2 interceptor for this** — rejected as a hidden write; the form owns the sequence.
+- The new row's uuid is read from the POST answer, never the contact's own uuid (an expanded parent in the answer must
+  not be linked as its own primary).
+
+## Change history
+- 2026-10-17 — Created for the TOGa Desk contact edit drawer (TRUE-82871). (jcardinal)

package/knowledge/INDEX.md

@@ -21,7 +21,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 103 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 104 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 90 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 26 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 22 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
@@ -34,7 +34,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **toga25-supply** (TOGa 2.5 Supply) — 26 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga25-iq** (TOGa IQ) — 1 doc(s) → [2.0/apps/toga25-iq/INDEX.md](2.0/apps/toga25-iq/INDEX.md)
 - **toga25-desk** (TOGa Desk 2.5) — 1 doc(s) → [2.0/apps/toga25-desk/INDEX.md](2.0/apps/toga25-desk/INDEX.md)
-- **toga25-blox** (TOGa Blox 2.5) — 4 doc(s) → [2.0/apps/toga25-blox/INDEX.md](2.0/apps/toga25-blox/INDEX.md)
+- **toga25-blox** (TOGa Blox 2.5) — 5 doc(s) → [2.0/apps/toga25-blox/INDEX.md](2.0/apps/toga25-blox/INDEX.md)
 - **toga-blox** (TOGa Blox) — 15 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 
 ## standalone framework

package/package.json

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