toga-ai 1.0.1068 → 1.0.1069

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

@@ -24,7 +24,7 @@
 | [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/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/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/package.json

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