toga-ai 1.0.536 → 1.0.538

package/knowledge/1.0/apps/library/features/startech-pcmaticb2b-sync.md

@@ -6,8 +6,8 @@ project: Library
 client: pcmaticb2b
 type: client-feature
 status: active
-updated: 2026-07-29
-owners: [snaredla]
+updated: 2026-08-10
+owners: [snaredla, mhammontree]
 files:
   - library/app/api/toga2.php
   - library/app/api/startechticket.php
@@ -59,6 +59,32 @@ $payload['ticketType'] = ['code' => $toga2TicketTypeCode];
 
 Both `PCS Ticket` and `TOGaDesk-PCS` map to `PCS` in TOGA 2.0.
 
+## Onboarding a new StarTech client — `STARTECH_TOGADESK_CLIENTS`
+
+`App_Api_Toga2::STARTECH_TOGADESK_CLIENTS` (`library/app/api/toga2.php`, top of the class) is the
+registry that identifies StarTech-integrated clients. It maps **TOGaDesk client id => the client's
+TOGA 2.0 API credentials**:
+
+```php
+const STARTECH_TOGADESK_CLIENTS = [
+    App_Model_TogaDesk_Ticket::TOGADESK_CLIENT_ID__PCMATICB2B => [
+        'clientUuid' => self::CLIENT_UUID_PCMATICB2B,
+        'apiUuid'    => self::API_UUID_PCMATICB2B,
+        'apiSecret'  => self::API_SECRET_PCMATICB2B,
+    ],
+];
+```
+
+- **A new row must be added per client onboard.** Consumers (e.g.
+  `getStartechSelectableTicketStageNames`) look the client up here and **short-circuit to an empty
+  result with no DB hit** when absent — so a missing row is a silent no-op (an empty status
+  dropdown), not an error. This is the operational step to remember.
+- The row's values are references to the per-client `CLIENT_UUID_*` / `API_UUID_*` /
+  `API_SECRET_*` class constants declared at the top of the same file — that is **where** the
+  credentials live. Do not reproduce their values in the KB, tickets, or logs (see the hardcoded-credentials
+  gotcha in [toga2-api-client-and-bridge](./toga2-api-client-and-bridge.md)).
+- Currently **one** row: TOGaDesk client **177** (PC Matic B2B).
+
 ## Gotchas
 
 - **Do not add a NULL early-return guard in this function.** NULL `c_escalateToStartech` means the ticket was created in TOGaDesk — it must still sync to TOGA 2.0. The Startech gate lives in `_Trait_Startech_Ticket::postPost`, not here.
@@ -93,16 +119,12 @@ Imports Startech (Easeedesk V3) config into TOGA 2.0 — users, groups, devices,
   the 1.0 → 2.0 payload. Both reference the client's 2.0 schema **by name** (from
   `App_Model_Client::getClientDatabaseNames()`) so the JOIN stays inside one client schema — do not use
   `qqJoinClientsTable(…, true)` here, its UNION-across-all-clients form would cross-match ids between
-  clients. StarTech clients are identified by `App_Api_Toga2::STARTECH_TOGADESK_CLIENTS`
-  (TOGaDesk client id => TOGA 2.0 client id); non-StarTech clients short-circuit with no DB hit.
-- 2026-07-29: Added two per-ticket-type stage helpers to `App_Api_Toga2` (see
-  `clients/pcmaticb2b/features/startech-per-ticket-type-stages.md`):
-  `getStartechSelectableTicketStageNames($togadeskClientId, $togadeskDepartmentId)` resolves the
-  agent-selectable stage names for TOGaDesk's status dropdown (department → ticket type via
-  `TicketTypes.c_togadeskTicketDepartmentId`, filtered by `c_isSelectable = 1`), and
-  `getStartechTicketStageUuid($ticketTypeName, $ticketStageName)` resolves a stage within a type for
-  the 1.0 → 2.0 payload. Both reference the client's 2.0 schema **by name** (from
-  `App_Model_Client::getClientDatabaseNames()`) so the JOIN stays inside one client schema — do not use
-  `qqJoinClientsTable(…, true)` here, its UNION-across-all-clients form would cross-match ids between
-  clients. StarTech clients are identified by `App_Api_Toga2::STARTECH_TOGADESK_CLIENTS`
-  (TOGaDesk client id => TOGA 2.0 client id); non-StarTech clients short-circuit with no DB hit.
+  clients. StarTech clients are identified by `App_Api_Toga2::STARTECH_TOGADESK_CLIENTS`;
+  non-StarTech clients short-circuit with no DB hit.
+- 2026-08-10: **Corrected** the description of `STARTECH_TOGADESK_CLIENTS` — it maps TOGaDesk client
+  id to the client's **TOGA 2.0 API credentials** (`clientUuid`/`apiUuid`/`apiSecret`, referencing the
+  `CLIENT_UUID_*`/`API_UUID_*`/`API_SECRET_*` class constants), **not** to a TOGA 2.0 client id as the
+  two 2026-07-29 entries stated. Added the onboarding section: a row must be added per client onboard
+  or the client silently short-circuits (empty stage list, no error). Also deduplicated the
+  accidentally-doubled 2026-07-29 entry. Observed while resolving a `_production` merge on TRUE-79401;
+  the const itself was authored by a teammate. (mhammontree)

package/knowledge/1.0/apps/library/features/toga2-api-client-and-bridge.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-05
+updated: 2026-08-10
 owners: [jcardinal, mhammontree, bala]
 files:
   - library/app/api/toga2.php
@@ -213,6 +213,10 @@ tickets) was **explicitly rejected** — see the gotcha about the single-recipie
    intact under a large merge. **Still open: whether it is deployed to the prod worker.**
    Review technique worth reusing: `git diff _production...HEAD -- <file>` isolates a ticket's real
    contribution from merge noise when an old branch is finally synced.
+   **Re-synced 2026-08-10** (`c64164fe`, pushed): `_production` merged into `TRUE-79401` again; the
+   only conflict was a positional collision in the class const block of `app/api/toga2.php` (this
+   ticket's `CUSTOMER_EMAIL_DELIMITER` landing next to incoming consts) — resolved by keeping both,
+   no logic change. Patch still intact; **deploy to the prod worker remains unverified.**
 2. **Beta verification of the nested write is outstanding.** Assert real
    `Client_Aig.ContactEmailAddresses` **row counts** (never the HTTP status), covering **both** a
    brand-new contact (CREATE) **and** a second entitlement for an **existing** contact (UPDATE).
@@ -361,6 +365,10 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
 
 ## Change history
 
+- 2026-08-10 — TRUE-79401 re-synced with `_production` (`c64164fe`, pushed); the sole conflict was a
+  positional const-block collision, resolved by keeping both sides. Patch intact; deploy still
+  unverified. `STARTECH_TOGADESK_CLIENTS` (credential registry, add a row per client onboard) is
+  documented on [startech-pcmaticb2b-sync](./startech-pcmaticb2b-sync.md). (mhammontree)
 - 2026-08-05 — Recorded that a 2.0 GET **silently truncates a nested child collection** (observed
   `itemFulfillmentItemUnits` 45 of 70) with no error — so verification/counts must read the child
   resource **flat + fully paginated** and use `meta.totalRecordCount`, never a single nested

package/knowledge/1.0/standards/backend-php.md

@@ -5,8 +5,8 @@ project: Library
 client: shared
 type: standard
 status: active
-updated: 2026-08-05
-owners: [jcardinal, rgirish, mhammontree]
+updated: 2026-08-06
+owners: [jcardinal, rgirish, mhammontree, ajean]
 files: []
 related:
   - ../apps/library/architecture.md
@@ -442,33 +442,44 @@ class Browser_Datagrid_Accounts extends Browser_Datagrid {
 * The `@` error-suppression operator is acceptable only for defensive file I/O (e.g. reading an optional cache file); do not use it to hide real errors.
 * Use structured logging to capture application behavior and errors.
 
-### PHP warnings throw — guard fragile I/O, do not rely on `!== false`
-
-The bootstrap sets `error_reporting(E_ALL)` and `App_Error::handleError` (`library/app/error.php`)
-converts **every** PHP warning into an `ErrorException`. Consequences you must design around:
-
-- Warning-emitting calls **throw at the call site** rather than returning their documented
-  failure value. `file_get_contents()` on an unreachable/403/timed-out URL raises an
-  `ErrorException` **inside** the call — so a following `if ($x !== false)` guard never runs.
-- In a loop (e.g. a cron), one such throw aborts the **entire** remaining batch, not just the
-  current item. This is especially dangerous in two-phase "stamp then act" crons where earlier
-  phases have already committed state.
-
-Wrap fragile I/O and return the failure value yourself:
-
-```php
-function safeFetchPdf(string $url) {
-    try {
-        return file_get_contents($url);
-    } catch (\ErrorException $e) {
-        error_log('PDF fetch failed: ' . $e->getMessage());
-        return false;
-    }
-}
-```
-
-Then guard each dependent step **independently** (not a joint `&&`) so one failure degrades
-gracefully instead of dropping unrelated work or crashing the loop.
+### A notice/warning cannot be contained by `try/catch` — and it jams queues
+
+**Canonical mechanics are above:** see
+[*Any PHP warning terminates the request — how to opt out locally*](#any-php-warning-terminates-the-request--how-to-opt-out-locally).
+`App_Error::handleError` does **not** throw; it calls `handleException`, which `exit`s. Two
+sanctioned opt-outs (a local `set_error_handler`, or
+`App_Error::setThrowExceptionsEnabled(false)` with a `finally` restore) are documented there.
+This section records what that means for **job/queue code** specifically.
+
+Additional verified detail:
+
+- **Both exit paths.** `handleException` ends in `exit` whether Sentry is absent
+  (`library/app/error.php` ~L407) or present (~L671). Apps that call `\Sentry\init` in
+  `_/app/framework.php` — `worker` included — take the Sentry path, so "Sentry is configured"
+  does **not** mean execution continues.
+- **The `return false;` after `exit;` in `handleError` is unreachable dead code.** Do not read
+  it as a signal that the handler returns control to the call site.
+- **A notice jams a queue exactly like an uncaught exception would.** In an inbox- or
+  queue-driven loop, any statement *after* the failure point — an ack, an
+  `$imap->deleteMessage()`, a status stamp — never executes, so the same item is re-read and
+  re-fails on every run, forever. Confirmed against production evidence: after the notice
+  fired, the importer made **zero** further api2 calls in that run.
+- **Diagnostic fingerprint:** an occurrence count that is an exact multiple of the job's
+  scheduled frequency (e.g. 20/hour for `*/3 * * * *`) means **one** poisoned item retried,
+  not many distinct failures.
+- **In job code, prevention beats containment.** Guard optional data with `isset()` before
+  reading it, and consume/ack the item in a `finally` (or under a `catch (Throwable)`) so a
+  genuine exception cannot strand it. You cannot wrap your way out of a notice.
+
+> **Existing guidance under review.** An earlier version of this section recommended
+> wrapping fragile I/O in `try { ... } catch (\ErrorException $e)` relying on the GLOBAL
+> handler to convert a warning. Given the `exit` above, that cannot work for a PHP
+> warning or notice — the process ends before the `catch`. Uses of that pattern need
+> **re-verifying** rather than assuming they are safe or assuming they are broken: the
+> call may be throwing a genuine exception, or installing a local handler. Known
+> occurrences to check: `clients/prudential/features/transmit-ordershipped-email.md`
+> (~L112-123), `clients/prudential/profile.md` (~L75). Prefer the local-handler pattern
+> from the canonical section above for anything new.
 
 ## Security Best Practices
 

package/knowledge/1.0/standards/framework-rules.md

@@ -5,8 +5,8 @@ project: Library
 client: shared
 type: standard
 status: active
-updated: 2026-06-16
-owners: [jcardinal]
+updated: 2026-08-06
+owners: [jcardinal, ajean]
 files: []
 related:
   - ../apps/library/architecture.md
@@ -114,9 +114,13 @@ repos is only query strings embedded in PHP code — not standalone migration fi
 
 ## PHP 8.x deprecations abort the request (audit before running on 8.5)
 
-The 1.0 framework's error handler promotes PHP **deprecation notices to `ErrorException`**,
-which aborts the request. On PHP 8.5, a single deprecated call in a live code path is therefore
-a hard failure, not a silent notice — it surfaces to users as a generic error.
+The 1.0 framework's error handler **terminates** on a PHP deprecation notice
+(`App_Error::handleError` → `handleException` → `exit`; it does not throw a catchable
+`ErrorException`), so the request/job dies where the deprecation fires. On PHP 8.5 a single
+deprecated call in a live code path is therefore a hard, uncontainable failure — a
+surrounding `try/catch` will not save it. See the back-end standard's
+*"Any PHP warning terminates the request — how to opt out locally"* section for the two
+sanctioned local opt-outs.
 
 - When porting or running 1.0 code on PHP 8.x, **audit for deprecated-in-8.x calls** in every
   reachable code path before deploy.

package/knowledge/2.0/apps/_underscore/features/error-reporting-issue-event.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-08-06
-owners: ["dfranks", "jcardinal", "mhammontree"]
+owners: ["dfranks", "jcardinal", "mhammontree", "ajean"]
 files:
   - _underscore/Error.php
   - _underscore/Database.php
@@ -466,6 +466,23 @@ gracefully — it silently deletes all observability for the whole tier. Any cha
   `varchar(255)` (`errorMessage`, `subject`) **throws** on `->save()`. Inside the handler's
   `catch(Throwable)` the throw is swallowed and the row is silently dropped — precisely when a
   long message matters most. Truncate to column width before `save()`.
+- **A truncated `errorMessage` reads as "the API returned nothing" — it did not.** When a
+  captured message is a `print_r`-dumped api2 response envelope, the `varchar(255)` cut lands
+  **exactly where `status`, `error.code` and `messages[]` begin**, so the console shows an
+  envelope with no verdict in it and the field looks empty rather than severed. (Observed: a
+  pasted error cut at precisely 255 chars sent an investigation after a phantom empty field.)
+  Escalation path when the console message stops mid-envelope:
+  **(1)** the **full** request/response is in the **client-scoped** `Logs_<Client>.Api`
+  (e.g. `Logs_Quad.Api`) — **not** core `Logs.Api`; **(2)** the original inbound payload is in
+  `Logs.Event.context` (for an email importer, the attachment content verbatim — this is how a
+  poison file was recovered). Pull `context` before the **7-day** `Event` retention purges it.
+- **`_Error::buildContext` redacts the DECODED token but not the RAW response string (OPEN
+  security note).** `access_token` is stripped from the decoded response object while the raw
+  `rawResponse` / `lastResponse` strings are stored intact, so live bearer JWTs reach
+  `Logs.Event.context` in **cleartext**. Two consequences: the raw strings need adding to the
+  redactor (in `_underscore/Error.php` **and** `library/app/error/capture.php` together, per the
+  gotcha above), and until then **never paste a `Logs.Event.context` or `Logs_<Client>.Api` row
+  into a ticket, chat, or knowledge doc** — those rows carry live tokens and customer PII.
 - **Hand-written SQL is what a table rename actually breaks — and it fails *after* the model
   succeeds.** The singular rename left plural literals in hand-written statements across four
   files, so `$issue->save()` succeeded and then `UPDATE Issues …` threw **1146** before the
@@ -563,6 +580,14 @@ clientUserId). **Neither was built.** As built instead:
 
 ## Change history
 
+- 2026-08-06 — Added two debugging/security notes found while unjamming the Quad PO/ASN importer:
+  (1) a `varchar(255)`-truncated `errorMessage` severs a dumped api2 envelope exactly at
+  `status`/`error.code`/`messages[]`, so escalate to the **client-scoped** `Logs_<Client>.Api`
+  for the full envelope and to `Logs.Event.context` (7-day purge) for the original payload;
+  (2) OPEN — `_Error::buildContext` redacts `access_token` in the decoded object but not in the
+  raw `rawResponse`/`lastResponse` strings, so `Event.context` holds cleartext JWTs; do not paste
+  those rows anywhere. (ajean)
+
 - 2026-08-06 — Recorded an **open defect**: error capture is entirely dead on sandbox-dev/beta
   because `Logs.Issue` there lacks the **`clickupPriority`** column, so the capture INSERT fails with
   MySQL 1054 and **no** Issue row, Event row, or ClickUp task is written — the only trace is

package/knowledge/2.0/apps/_underscore/features/tracking-number-bridges.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-05
-owners: ["jcardinal", "mhammontree", "dfranks", "apeterson", "bala"]
+updated: 2026-08-06
+owners: ["jcardinal", "mhammontree", "dfranks", "apeterson", "bala", "tcox"]
 files:
   - api2/Component/Api/V2/V2.php
   - _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php
@@ -177,9 +177,29 @@ returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTracki
   `toga25-supply/sync_compasscanada_schema.sql` against `Client_CompassCanada` (local-only — prod
   already has the tables). See the
   [local-DB-refresh-from-beta workflow](../workflows/local-db-refresh-from-beta.md).
+- **⚠ Clients that were not hand-migrated still carry `TableViewJoins` pointing at the DELETED
+  RecordFields — and nothing validates them until a user opens the view.** The per-client TableView
+  repointing was done one client at a time (Compass, NYCHH, Quad); a client onboarded before it, or
+  skipped, keeps joins on dropped ids and its views **500** — first
+  `table-views/meta` with *"Model build for primary key id '1431' for `_Model_Core_RecordField` … 0
+  rows"*, then the data query with *"Unknown column … in 'on clause'"* once the missing bridge join
+  record leaves the alias undefined. **`Client_Elite` has 11 such references across 9 views, in
+  production as well as sandbox** — see
+  [Elite supply2 TableView config drift](../../../clients/elite/features/supply2-tableview-config-drift.md)
+  for the full map and the NYCHH-mirroring fix. Before switching on a supply surface for a client
+  onboarded before 2026-06, diff its `TableViewJoins` against a migrated client. Note the same
+  audit found `sales-order-shipments` (join 10) referencing dead RecordField **211 in
+  `Client_Nychh` too** — that view is broken platform-wide and needs a backend decision, not a
+  copy.
 - **Porting the item-fulfillment TableView fix to another client is two independent decisions, not a copy-paste.** The **re-root** (Units 31 → ItemFulfillmentItems 29 + OUTER unit chain) is universally portable and fixes the "0 records" bug everywhere. The **tracking source is client-specific**: Compass writes one tracking number per item fulfillment at the **item level (318)**, so its views read 318. Other clients populate different bridge levels — verify with `SELECT COUNT(*)` per bridge before choosing. As of 2026-06-19, **record 318 is empty in `Client_Nychh` and `Client_Quad`**; their tracking lives at the **IF/shipment level (317)** (covers IFIs: NYCHH 7955/10049 ≈ 79%, Quad 4878/4967 ≈ 98%) and the **unit level (319)** (≈ 7–9% — serialized only). Copying Compass's 318 join into a client that doesn't write 318 yields a structurally-correct view with permanently blank tracking until 318 is backfilled. (NYCHH's pre-fix view pointed at the now-deleted record 41 = old IF-level/package bridge, i.e. it originally intended IF-level 317.)
 
 ## Change history
+- 2026-08-06 — Recorded that the per-client TableView repointing left **unmigrated clients broken**:
+  `Client_Elite` still has 11 references to deleted RecordFields (211/321/932/358/1431) across 9
+  views in **prod and sandbox**, so its views 500 on `table-views/meta` and then on the data query
+  once the bridge join record (319 / 289) is missing. Added the pre-go-live check (diff a new
+  client's `TableViewJoins` against a migrated one) and noted `sales-order-shipments` join 10
+  references dead 211 in `Client_Nychh` as well. (tcox)
 - 2026-08-05 — Recorded that the 1.0 `App_Api_Toga2::syncItemFulfillmentFromNetsuite` full reconcile
   now maintains **all three** IF bridges (317/318/319) and, when pruning units/items NetSuite dropped,
   **deletes their bridge links first** because the bridge parent FKs are `RESTRICT` (no cascade) —

package/knowledge/2.0/apps/_underscore/features/units-for-items-for-purchase-orders.md

@@ -6,10 +6,12 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-22
-owners: ["bala"]
+updated: 2026-08-06
+owners: ["bala", "tcox"]
 files: []
-related: []
+related:
+  - ./tracking-number-bridges.md
+  - ../../../clients/elite/features/supply2-tableview-config-drift.md
 ---
 
 ## Summary
@@ -82,7 +84,19 @@ None — uniform. The linkage structure is framework-level and identical across
   sales order (over/under-attribution), because attribution is by PO line, not by the
   fulfillment that shipped the unit.
 
+- **A 500 here is usually stale per-client view config, not missing data.** This view's joins were
+  repointed onto the bridge records (319 tracking, 289 `SalesOrderItems_PurchaseOrderItems`) per
+  client. A client that never got that migration 500s on `table-views/meta` (*"Model build for
+  primary key id '1431' for `_Model_Core_RecordField` … 0 rows"*) and then on the data query
+  (*"Unknown column `SalesOrderItems_PurchaseOrderItems.salesOrderItemId` in 'on clause'"*).
+  Confirmed on `Client_Elite` (view 17) — see
+  [Elite TableView config drift](../../../clients/elite/features/supply2-tableview-config-drift.md).
+  Check the view config before investigating the linkage paths above.
+
 ## Change history
+- 2026-08-06 — Added the gotcha that a 500 on this view is usually **stale per-client
+  `TableViewJoins`** left behind by the bridge migrations (records 319 / 289), not a data-linkage
+  problem; confirmed on `Client_Elite` view 17. (tcox)
 - 2026-06-22 — Documented the two-path units linkage model behind the
   units-for-items-for-purchase-orders view and why the receipt-only traversal hides
   fulfillment-only units. (bala)

package/knowledge/2.0/apps/_underscore/workflows/local-db-refresh-from-beta.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: workflow
 status: active
-updated: 2026-07-27
-owners: ["apeterson", "mhammontree"]
+updated: 2026-08-06
+owners: ["apeterson", "mhammontree", "tcox"]
 files:
   - api2/Config/
   - _underscore/Loader.php
@@ -59,6 +59,15 @@ Order matters — dump first so a failed dump never wipes a local schema it can'
 
 ## Gotchas / known issues
 
+- **"Beta" and "dev-sandbox" are the same cluster — confirm it in `Core.DatabaseHosts`, not in old
+  migrations.** `Core.DatabaseHosts` maps environment **`beta`** for `Client_*` schemas to the
+  **sandbox-dev** RDS cluster (`sandbox-dev.cluster-…us-east-1.rds.amazonaws.com`,
+  a.k.a. `dev.sandbox.database.togahub.com`). Practical consequences: a frontend running locally
+  against `VITE_API=https://api.beta.togahub.com/v2` authenticates and reads **dev-sandbox** data,
+  so seeding a test user there means inserting into the dev-sandbox `Client_<Id>`; and in the DB MCP
+  the environment to query is **`dev-sandbox`** (`client-beta` exposes no schemas). 2024-era
+  onboarding SQL that shows beta on a us-west-2 `client-cluster` is stale — that has been
+  consolidated.
 - **Beta `admin` lacks `RELOAD` → `--single-transaction` fails.** The managed sandbox account
   cannot `FLUSH TABLES WITH READ LOCK`, so the default `mysqldump --single-transaction` dies with
   `Couldn't execute 'FLUSH TABLES WITH READ LOCK': Access denied ... (1045)`. **Fix:** drop
@@ -105,6 +114,10 @@ Order matters — dump first so a failed dump never wipes a local schema it can'
 
 ## Change history
 
+- 2026-08-06 — Recorded that environment **`beta` resolves to the dev-sandbox cluster** in
+  `Core.DatabaseHosts` for `Client_*` schemas, so an app pointed at `api.beta.togahub.com` is
+  reading dev-sandbox data and the DB MCP environment to query is `dev-sandbox` (not
+  `client-beta`, which exposes no schemas). (tcox)
 - 2026-07-27 — TRUE-79191: added the reverse-drift gotcha — pulling updated `_underscore` models from
   prod **without** applying the matching `dbchanges2` migrations locally throws `1054 Unknown column`
   (e.g. `Items.isFulfillable` from the 2026-07-17 migration); apply pending migrations or reset the

package/knowledge/2.0/apps/api2/features/v2-api-error-codes.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-30
-owners: [mhammontree, tcox, jcardinal]
+updated: 2026-08-10
+owners: [mhammontree, tcox, jcardinal, ajean]
 files:
   - api2/Component/Api/V2/V2.php
   - api2/Component/Api/V2/Response/Response.php
@@ -97,6 +97,46 @@ migration instead of re-deriving it. All field/script ACL rows live in the **CLI
    DB fully migrated. On a local dev box with PHP opcache disabled a branch switch takes effect
    immediately (files are read fresh per request) — no Apache restart needed.
 
+7. **`EV-12` can just be a mis-prefixed field name — check native vs. custom before anything
+   else.** The `c_` prefix is **not** cosmetic: `c_foo` and `foo` are different field names, and
+   a `c_`-prefixed name that has no custom-field registration simply does not exist, so api2
+   rejects **the entire write** (not just that key). This bites hardest on records where *some*
+   sibling keys genuinely are custom — e.g. `Client_Quad.Units` carries custom
+   `c_hostIdentifier` / `c_pkIdentifier` next to **native** `serialNumber`, `assetTag` and
+   `macAddress`, and sending `c_macAddress` failed the whole item fulfillment with `EV-12`.
+   Diagnose by running `SHOW COLUMNS` on the tenant table: a real column name → send it
+   **unprefixed**; no column → it must be a registered custom field to be sendable at all.
+   Verify **every** key in a nested payload, not just the one you changed.
+
+8. **`EV-12` on a *lookup-by-name* means ambiguous, not missing.** A nested payload that
+   identifies a parent by a non-unique field (e.g. `shippingMethod: {name: 'Courier'}` where
+   the tenant's `ShippingMethods` holds two `Courier` rows under different carriers) cannot
+   resolve, and reads as a validation failure on the child (`trackingNumber`). Before hunting
+   for a missing record, check for **duplicates** — especially where the caller has its own
+   create-if-missing path, which is how the duplicate usually got there. Fix by narrowing the
+   identifier (nest the carrier), not by re-creating the parent.
+
+9. **Turn an `EO-1` into a stack trace via `error.id`.** The 500 envelope carries
+   `error.id` like `"8K-6"`. The part **before the dash** is `Logs.Issue.reference` —
+   `SELECT * FROM Logs.Issue WHERE reference = '8K'` gives the full `errorMessage` and stack
+   trace. The envelope itself tells you nothing useful; always go to `Logs.Issue`.
+   Corollary: if `transactionId`, `authority` and `audience` are **all NULL** in the error
+   envelope, the request failed **before client context was established**.
+
+10. **A "wrong client" bearer token looks like a payload bug.** POSTing a **Rate**-shaped
+    entitlement payload while holding an **AIG** token routes into
+    `_Model_Aig_Entitlement::prePost()` and dies with
+    `Undefined property: stdClass::$partNumber` — which reads as a malformed payload, not an
+    auth problem. **Switching Postman folders does NOT change the token**: it lives in an
+    environment variable and must be re-minted by re-running the auth request. Cheap
+    verification before debugging anything else — send any `GET` and check
+    **`audience.client`** in the response envelope.
+
+11. **api2 matches nested objects by `uuid` ONLY.** Browser payloads often identify a related
+    record by a client-custom key (e.g. Rate's `c_borrowerId` for the customer). Replaying such
+    a payload server-side will **create a duplicate** rather than match the existing record.
+    When replaying or backfilling, rewrite every nested reference to use `uuid`.
+
 ## BREAKING (2026-07-30): `error` is now an object, not a bare string
 
 The V2 envelope's `error` changed from a bare string (`"EO-1"`) to an **object**:
@@ -182,6 +222,21 @@ Full mechanics:
 
 ## Change history
 
+- 2026-08-10 — TRUE-80575: added diagnosis notes 9-11 from debugging a Rate entitlement
+  replay — (9) `error.id`'s prefix before the dash **is** `Logs.Issue.reference`, so an `EO-1`
+  500 becomes a real stack trace via `SELECT * FROM Logs.Issue WHERE reference = '…'`, and
+  all-NULL `transactionId`/`authority`/`audience` means the failure preceded client context;
+  (10) a **wrong-client bearer token** masquerades as a payload bug (Rate payload + AIG token →
+  `Undefined property: stdClass::$partNumber` from `_Model_Aig_Entitlement::prePost()`), and
+  Postman folders do not switch tokens — verify `audience.client` on any GET first; (11) api2
+  matches nested objects by **`uuid` only**, so replaying a browser payload that references a
+  record by a custom key (`c_borrowerId`) creates a duplicate. (mhammontree)
+- 2026-08-06 — Added two `EV-12` diagnosis notes from the Quad PO/ASN importer: (6) a
+  mis-prefixed field name (`c_macAddress` for the **native** `Units.macAddress` column) makes
+  api2 reject the whole write — verify every nested key against `SHOW COLUMNS`, since custom
+  and native keys sit side by side on the same record; (7) `EV-12` on a lookup-by-name means
+  the parent is **ambiguous** (duplicate `ShippingMethods` rows named `Courier`), not missing —
+  narrow the identifier rather than re-creating the parent. (ajean)
 - 2026-08-04 — Recorded the catch-order trap from `_Exception_Business` now extending
   `_Exception_Validation` (business conditions answer 4xx and are still captured, but any
   `catch (_Exception_Validation …)` must test business **first** or they go unrecorded), and the

package/knowledge/2.0/apps/toga2-commerce/INDEX.md

@@ -6,7 +6,7 @@
 | [Cart Bundle Submission & the bundleUuid Identity Contract](features/cart-bundle-submission-and-identity.md) | How cart **bundles** (kits) are turned into `SalesOrderItems` when a cart is submitted or an existing order is edited, and the **identity-field contract** every | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts, src/utils/formatSalesOrderBundlesFromApi.ts, src/stores/useCartStoreZu.ts, src/pages/OrderDetails/helpers/formatSalesOrderDataFromLocalStorage.ts, src/pages/OrderDetails/view/components/OrderItems.tsx |
 | [Cart Notification Emails — duplicate prevention](features/cart-notification-emails.md) | On the cart "Notifications" section a user can add CC email addresses to an order. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/stores/useEmailOptionsStore.ts, src/stores/useCartSalesQuoteZu.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts |
 | [Cart Page — config-driven form architecture (current state + planned refactor)](features/cart-page-config-architecture.md) | The Cart page (`src/pages/Cart/`) is the most config-heavy page in `toga2-commerce`. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/pages/Cart/view/cartForm/CartFormSection.tsx, src/pages/Cart/view/cartForm/CartFormRenderer.tsx, src/pages/Cart/view/EditCart.tsx, src/pages/Cart/view/EditOrder.tsx, src/pages/Cart/viewModel/useEditOrderOrEditCartViewModel.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts, src/hooks/useAssignClientFields.ts |
-| [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Almost no user-facing text, field layout, or page config is hard-coded in `toga2-commerce`. | src/pages/Account/view/MySettingsView.tsx, src/fieldsConfig/index.ts, src/fieldsConfig/getClientLoginFields.ts, src/fieldsConfig/clientFields/COMPASS.json, src/fieldsConfig/clientFields/COMPASSCANADA.json, src/fieldsConfig/clientFields/QUAD.json, src/pages/Cart/api/CartApi.ts, src/hooks/useAuthenticationFlow.ts, src/contexts/AuthContext.tsx, src/pages/Login/viewModel/useLoginPageViewModel.ts, src/hooks/useAssignClientFields.ts, src/hooks/useDynamicConditionalFieldOptions.ts, src/stores/useFieldsStore.ts, src/components/BaseDetailField/BaseDetailField.tsx, src/components/NavIcons/NavIconItem.tsx, src/components/Submenus/AlertSubmenu.tsx, src/components/Submenus/types.ts, src/pages/Account/AccountPage.tsx, src/pages/Account/view/MyOrdersView.tsx, src/pages/GetSupport/GetSupportPage.tsx, src/pages/GetSupport/viewModel/useGetSupportViewModel.ts, src/queries/queries.ts, src/App.tsx, src/pages/Filter/FilterPage.tsx, src/pages/Filter/viewModel/FIELDS/COMPASS/ENGLISH/USER/FILTERPAGEFIELDS.json |
+| [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Almost no user-facing text, field layout, or page config is hard-coded in `toga2-commerce`. | src/pages/Account/view/MySettingsView.tsx, src/contexts/helpers/getLoginSettings.ts, src/pages/Account/viewModel/useAccountViewModel.ts, src/fieldsConfig/index.ts, src/fieldsConfig/getClientLoginFields.ts, src/fieldsConfig/clientFields/COMPASS.json, src/fieldsConfig/clientFields/COMPASSCANADA.json, src/fieldsConfig/clientFields/QUAD.json, src/pages/Cart/api/CartApi.ts, src/hooks/useAuthenticationFlow.ts, src/contexts/AuthContext.tsx, src/pages/Login/viewModel/useLoginPageViewModel.ts, src/hooks/useAssignClientFields.ts, src/hooks/useDynamicConditionalFieldOptions.ts, src/stores/useFieldsStore.ts, src/components/BaseDetailField/BaseDetailField.tsx, src/components/NavIcons/NavIconItem.tsx, src/components/Submenus/AlertSubmenu.tsx, src/components/Submenus/types.ts, src/pages/Account/AccountPage.tsx, src/pages/Account/view/MyOrdersView.tsx, src/pages/GetSupport/GetSupportPage.tsx, src/pages/GetSupport/viewModel/useGetSupportViewModel.ts, src/queries/queries.ts, src/App.tsx, src/pages/Filter/FilterPage.tsx, src/pages/Filter/viewModel/FIELDS/COMPASS/ENGLISH/USER/FILTERPAGEFIELDS.json |
 | [Config-Driven Expedited Shipping Gating (Cart)](features/expedited-shipping-gating.md) | On the toga2-commerce **Cart** page, expedited shipping options (**"2nd Day EOB"** and **"Next Day Air"**) are only offered in the *Shipping Method* dropdown wh | toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/CartPage.tsx |
 | [Filter / Search-Results Page & the Two Search Entry Points](features/filter-search-results-page.md) | The storefront has **two distinct search entry points that render the same card component through completely different code paths and different FIELDS files**. | src/pages/Filter/FilterPage.tsx, src/pages/Filter/viewModel/useFilterViewModel.ts, src/pages/Filter/viewModel/FIELDS/COMPASS/ENGLISH/USER/FILTERPAGEFIELDS.json, src/pages/Filter/viewModel/FIELDS/COMPASSCANADA/FRENCH/USER/FILTERPAGEFIELDS.json, src/pages/Filter/viewModel/FIELDS/QUAD/ENGLISH/BUYER/FILTERPAGEFIELDS.json, src/components/Header/Header.tsx, src/pages/Home/view/components/BundlesSection.tsx, src/pages/Home/viewModel/FIELDS/COMPASS/ENGLISH/USER/HOMEPAGEFIELDS.json, src/components/Cards/BundleViewCard.tsx, src/utils/renderBadge.tsx, src/hooks/useAssignClientFields.ts |
 | [Multi-Tenant Resolution & Theming](features/multi-tenant-theming.md) | `toga2-commerce` serves multiple clients from one codebase. | src/themeConfig/themes.json, src/themeConfig/ThemeContext.tsx, src/themeConfig/types.ts, src/components/ThemeSwitcher/ThemeSwitcher.tsx, src/components/AuthLayout/AuthLayout.tsx, src/api/axiosInstance.ts, src/contexts/AuthContext.tsx, tailwind.config.js |

package/knowledge/2.0/apps/toga2-commerce/features/client-fields.md

@@ -6,10 +6,12 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-07-28
+updated: 2026-08-06
 owners: ["apeterson", "tcox", "bala"]
 files:
   - src/pages/Account/view/MySettingsView.tsx
+  - src/contexts/helpers/getLoginSettings.ts
+  - src/pages/Account/viewModel/useAccountViewModel.ts
   - src/fieldsConfig/index.ts
   - src/fieldsConfig/getClientLoginFields.ts
   - src/fieldsConfig/clientFields/COMPASS.json
@@ -68,7 +70,10 @@ resolved per tenant, per language, and per role**. There are **two layers**:
 ```
 
 - `languageSwitcher.isEnabled` — **only COMPASSCANADA is `true`** (English/French). COMPASS and
-  QUAD are `false`.
+  QUAD are `false`. This is a **hard branch-reachability fact**, not a preference: it gates the
+  *entire first branch* of `getLoginSettings.ts`, so that branch is **unreachable for Compass USA**
+  and QUAD. See "Login-settings branches" below before judging whether a `getLoginSettings` change
+  affects US or CA.
 - `userApiFields` — the allow-list of user columns fetched at login; importantly it includes the
   tenant's **role flags**: COMPASS/COMPASSCANADA carry `_isAdmin`, `_isSupervisor`, `_isSuperAdmin`;
   QUAD carries `_isGlobalAdmin`, `_isItShopper`, `_isBuyer`. All include `_personaIds`. This key is
@@ -91,6 +96,33 @@ Resolved by **`src/fieldsConfig/getClientLoginFields.ts`** — a `switch(client)
 **default is `COMPASS`** (not DEFAULT). Called from `AuthContext` as `getClientLoginFields(host)`.
 The `languageSwitcher.isEnabled` value feeds the login-settings branch in `getLoginSettings.ts`.
 
+### Login-settings branches (`src/contexts/helpers/getLoginSettings.ts`)
+
+The top-level shape is `if (languageSwitcher.isEnabled) … else if (isPersonaSwitcherEnabled) … else …`,
+and each leaf calls `setUser({ ...userData, contactUuid, _personaOptions })`. Two facts decide who is
+affected by an edit here:
+
+- **Branch 1 (language) is COMPASSCANADA-only** — COMPASS/QUAD `languageSwitcher.isEnabled` is
+  `false`, so a change confined to branch 1 **cannot** affect Compass USA.
+- **Within Canada, the "no saved language" sub-branch is the common path.** Only **69 of 4,655**
+  active Canada users have a stored language preference (`UserGlobalSettings` page `language`), so
+  **~98% of Canada logins** take the `else` sub-branch that opens the settings modal.
+
+> **Known defect (production) — Canada My Account shows a blank Persona field.** That
+> "no saved language" sub-branch was the **only one of the seven `setUser` calls** in
+> `getLoginSettings` not passing `_personaOptions`. All **8** Canada `MYACCOUNTFIELDS` configs
+> (EN + FR × 4 roles) display a Persona field, and
+> `src/pages/Account/viewModel/useAccountViewModel.ts` (~line 311) guards on `user._personaOptions`
+> before populating it. **Nothing else sets it for those users** — the persona switcher is QUAD-only
+> via `settingsKey`, and `NavIconList` only runs under View-As — so the field renders blank. This is
+> a real defect, not cosmetic: Canada has 34 personas, 7,017 users with personas, 1,461 with more
+> than one. A one-line fix exists on `TRUE-80672` / `_beta` (commit `5313a9b1`, "populate
+> `_personaOptions` on the no-language login path") but is **not in `_production`** — verify the
+> branch before assuming it is fixed. Related: the persisted-store caveat in
+> [Language-sensitive React Query caches](#language-sensitive-react-query-caches-language_sensitive_query_keys)
+> — `_personaOptions` lives in the persisted Zustand user store, so if it is never written at login,
+> no cache invalidation will heal it.
+
 ### `fetchUsersApiFields` / `fetchUserApiFields` and the config-driven Cart fetches (C6)
 
 `fetchUsers()` in `src/pages/Cart/api/CartApi.ts` no longer hardcodes its field list. It resolves it
@@ -378,6 +410,14 @@ on switch.
   slip. Do not "reconcile" the two lists.
 
 ## Change history
+- 2026-08-06 — Added a **Login-settings branches** section for `getLoginSettings.ts`: branch 1 is
+  gated by `languageSwitcher.isEnabled` and is therefore **unreachable for COMPASS/QUAD**, and within
+  Canada only **69 of 4,655** active users have a stored language, so ~98% take the "no saved
+  language" sub-branch. Recorded the resulting **production defect** — that sub-branch was the only
+  one of seven `setUser` calls omitting `_personaOptions`, so Canada My Account renders a blank
+  Persona field (all 8 COMPASSCANADA `MYACCOUNTFIELDS` show it; `useAccountViewModel` guards on
+  `user._personaOptions`; nothing else populates it). Fix `5313a9b1` is on `TRUE-80672`/`_beta` only,
+  **not `_production`**. (bala)
 - 2026-07-28 — Documented two failure modes found while fixing the header-search kit card: (1) there is
   **no fallback for an individual key** inside a present page JSON — a missing key silently yields
   `undefined` (empty uncolored badge, `"3 undefineds"`), and key names differ per page

package/knowledge/2.0/apps/toga2-supply/INDEX.md

@@ -5,4 +5,4 @@
 | [TOGa Supply (toga2-supply) Architecture](architecture.md) | `toga2-supply` is the **React + Vite frontend** for TOGa Supply — warehouse fulfillment tooling (shipment selection, fulfill & ship against carrier APIs, NetSui | toga2-supply/src/api/toga.ts, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx |
 | [Fulfill & Ship](features/fulfill-and-ship.md) | Fulfill & Ship lets a warehouse user select sales-order line items, enter serials, pick a carrier/method, and in one action: create the Item Fulfillment records | _underscore/Model/Client/Measure.php, _underscore/Model/Client/TrackingNumber.php, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/getEditShipmentFormOptions.ts, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/validateFormOnSubmit.ts, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/checkDimensions.ts, toga2-supply/src/components/ui/Tables/BasicTable/BasicTable.tsx, toga2-supply/src/components/ui/Tables/types.ts, toga2-supply/src/components/ui/GoogleMapsLink.tsx, toga2-supply/src/pages/ShipmentItems/view/forms/ShipmentItemsTable.tsx, toga2-supply/src/pages/ShipmentItems/api/ShipmentItemsApi.ts, toga2-supply/src/pages/ShipmentItems/types.ts, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/RETURNLABELFIELDS.json, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/components/ui/BaseInput/UnitSelect.tsx, toga2-supply/src/pages/EditShipment/view/modals/SerialNumbersModal.tsx, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/pages/EditShipment/view/components/SelectedShipmentItemsTable.tsx, toga2-supply/src/pages/EditShipment/view/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/DUMMYUPDATESHIPMENTFIELDS.json, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/tailwind.config.cjs, toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx, toga2-supply/src/styles/index.scss, toga2-supply/src/components/ui/BaseInput/BaseInput.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/EditShipment/viewModel/signatureTypes.ts, toga2-supply/src/pages/EditShipment/view/modals/SelectReturnAddressModal.tsx, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/formatShipmentData.ts, toga2-supply/src/pages/EditShipment/types.ts, toga2-supply/src/pages/Shipments/view/ShipmentsPage.tsx, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, toga2-supply/src/pages/Shipments/types.ts, toga2-supply/src/pages/FulfilledShipments/view/FulfilledShipmentsPage.tsx, toga2-supply/src/components/ui/CardTable/CardTable.tsx, toga2-supply/src/components/ui/CardTable/types.ts, toga2-supply/src/assets/pen-line.svg, _underscore/Model/Client/ItemFulfillment.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php |
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-supply` (React + Vite) builds and deploys on **AWS Amplify**. | toga2-supply/amplify.yml, toga2-supply/.gitattributes, toga2-supply/.github/workflows/sync-stage-environments.yml, toga2-supply/.env.qc-security |
-| [Onboarding a client to the supply2 frontend (host-scoping)](workflows/client-host-scoping.md) | How a new tenant becomes a "client" in the `toga2-supply` frontend. | toga2-supply/src/stores/useHostNameStore.ts, toga2-supply/src/hooks/useHostName.tsx, toga2-supply/src/hooks/usePageDetails.tsx, toga2-supply/src/hooks/usePageListDetails.tsx, toga2-supply/src/components/layout/SlideMenu/SlideMenu.tsx, toga2-supply/src/utils/handleClientAuthentication.ts, toga2-supply/src/App.tsx, toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts, toga2-supply/src/pages/Inventory/listing/InventoryPage.tsx, toga2-supply/src/api/toga.ts |
+| [Onboarding a client to the supply2 frontend (host-scoping)](workflows/client-host-scoping.md) | How a new tenant becomes a "client" in the `toga2-supply` frontend. | toga2-supply/src/stores/useHostNameStore.ts, toga2-supply/src/utils/resolveClientHostName.ts, toga2-supply/src/hooks/useHostName.tsx, toga2-supply/src/hooks/usePageDetails.tsx, toga2-supply/src/hooks/usePageListDetails.tsx, toga2-supply/src/components/layout/SlideMenu/SlideMenu.tsx, toga2-supply/src/utils/handleClientAuthentication.ts, toga2-supply/src/App.tsx, toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts, toga2-supply/src/pages/Inventory/viewModel/FIELDS/INVENTORYPAGEFIELDS.ts, toga2-supply/src/pages/Inventory/listing/InventoryPage.tsx, toga2-supply/src/pages/Inventory/listing/InventorySubTablePage.tsx, toga2-supply/src/api/toga.ts, toga2-supply/package.json |