toga-ai 1.0.497 → 1.0.499

package/knowledge/1.0/apps/library/INDEX.md

@@ -14,4 +14,4 @@
 | [NetSuite SuiteQL/REST Shim — Field Semantics](features/netsuite-suiteql-rest-shim.md) | `App_Api_Netsuite_Rest` is the REST/SuiteQL replacement for the deprecated NetSuite SOAP toolkit. | library/app/api/netsuite/rest.php |
 | [NetSuite Sync Alert Monitor (App_SystemMonitor_NetSuiteIntegration)](features/netsuite-sync-alert-monitor.md) | `App_SystemMonitor_NetSuiteIntegration` (`library/app/systemmonitor/netsuiteintegration.php`, title **"NetSuite Sync Alert"**) is a 1.0 system monitor that watc | library/app/systemmonitor/netsuiteintegration.php, worker/crons/infrastructure/system_monitors.php |
 | [Startech PC Matic B2B Sync (library)](features/startech-pcmaticb2b-sync.md) | `library/app/api/toga2.php` handles bidirectional ticket sync for PC Matic B2B between TOGaDesk 1.0 and TOGA 2.0. | library/app/api/toga2.php, library/app/api/startechticket.php, worker/crons/toga2/startech/common_import_supporting_records.php |
-| [App_Api_Toga2 — TOGa2 API Client & 1.0↔2.0 Sync Bridge](features/toga2-api-client-and-bridge.md) | `App_Api_Toga2` (`library/app/api/toga2.php`, ~8400 lines) is the **1.0-side client for the TOGa 2 (`_underscore`/api2) public API** *and* the home of the cross | library/app/api/toga2.php, worker/crons/toga2/aig/sync_togasupply_aig.php, worker/crons/toga2/wje/sync_togasupply_wje.php |
+| [App_Api_Toga2 — TOGa2 API Client & 1.0↔2.0 Sync Bridge](features/toga2-api-client-and-bridge.md) | `App_Api_Toga2` (`library/app/api/toga2.php`, ~8400 lines) is the **1.0-side client for the TOGa 2 (`_underscore`/api2) public API** *and* the home of the cross | library/app/api/toga2.php, worker/crons/toga2/aig/sync_togasupply_aig.php, worker/crons/toga2/wje/sync_togasupply_wje.php, test/@Mark/AIG/test_multi_email.php |

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

@@ -12,9 +12,12 @@ files:
   - library/app/api/toga2.php
   - worker/crons/toga2/aig/sync_togasupply_aig.php
   - worker/crons/toga2/wje/sync_togasupply_wje.php
+  - test/@Mark/AIG/test_multi_email.php
 related:
   - ../../../2.0/apps/api2/features/nested-relationship-writes.md
   - ../../../clients/aig/features/entitlement-intake.md
+  - ../../test/features/static-no-db-regression-harness.md
+  - ../../../2.0/apps/dbchanges2/workflows/local-vs-prod-mysql-config-parity.md
   - netsuite-suiteql-api-reference.md
   - netsuite-suiteql-rest-shim.md
   - ../../worker/features/netsuite-togasupply-per-client-sync.md
@@ -138,7 +141,28 @@ Correct inbound shape:
 ```
 
 The primary **may** be repeated inside the collection — `syncContactToToga1Customer` de-dupes with
-`array_unique`.
+`array_unique` — and AIG **should** repeat it: if the collection carries extras but **omits** the
+primary, the primary is **not** re-added (the fallback fires only on a *fully empty* list), so the
+1.0 field ends up holding the secondary/tertiary **without** the main address.
+
+**A wrong shape degrades silently to primary-only — it does NOT blank the field (corrected
+2026-08-03, proven by the static harness).** With an array of bare strings, `array_column()` finds
+no `emailAddress` key → empty list → **the primary-email fallback fires** → the stored value is
+exactly the primary address, **byte-identical to correct single-email behavior.** So there is **no
+observable difference between "AIG sent the wrong shape" and "AIG hasn't enabled the feature yet"**
+— strictly worse for diagnosis than a blanked field. The **only** reliable verification signal is
+the child row count in `Client_Aig.ContactEmailAddresses`: not the HTTP status, and **not** the 1.0
+`Customers.emailAddress` value.
+
+**Storage is bounded — "send as many as you like" is FALSE at the 1.0 layer.** With `'; '` joining
+and ~47-char business addresses, measured lengths against the `varchar(255)` column: 2 addr = 96,
+3 = 145, 5 = 243 chars (all fit); **8 = 390 and 10 = 489 chars → OVERFLOW.** So the practical cap
+is roughly **6–7 business-length addresses.** The committed scope (secondary + tertiary ⇒ 3
+addresses ≈ 145 chars) is comfortably safe, but the 2.0 nested collection is structurally
+**unbounded** while the 1.0 column is not — the "1, 2, 3 or 10 all work with no change on our side"
+pitch is true of 2.0 storage only, and must be qualified for 1.0. Overflow behavior is itself
+machine-dependent (silent truncation under an empty `sql_mode`, `ERROR 1406` under strict mode) —
+see [local vs prod MySQL config parity](../../../2.0/apps/dbchanges2/workflows/local-vs-prod-mysql-config-parity.md).
 
 **Three distinct layers — only the last one is delimited.** Conflating them is the easy mistake:
 
@@ -164,8 +188,18 @@ tickets) was **explicitly rejected** — see the gotcha about the single-recipie
 
 ### Open items (TRUE-79401)
 
-1. Confirm the library change is **merged and deployed to the prod worker** (git/deploy state not
-   verified as of 2026-08-03).
+1. **Merged: YES. Deployed: still unverified.** Verified 2026-08-03: branch `TRUE-79401`
+   (`5aca31ea`) is **fully merged up with `_production`** (`_production` is an ancestor of HEAD,
+   working tree clean, local `_production` == `origin/_production` as of the last fetch — no network
+   fetch was run). The ticket's own patch is **still +17 / −2 in `app/api/toga2.php`** against
+   `_production`: the two merge commits (`90b4178b`, `5aca31ea`) pulled in ~404 insertions of
+   **other** tickets' work (TRUE-80408/80374, plus the error-capture and ServiceNow-OAuth commits)
+   and **none** of them touched `syncContactToToga1Customer`, the `/contacts` fetch `fields` list, or
+   any TRUE-79401 identifier. `php -l` clean on PHP 7.2.33; harness drift guard OK; 12/12 cases pass
+   after the merges. **A reviewer should not be alarmed by the file's churn** — the small patch is
+   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.
 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).
@@ -250,7 +284,9 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
   framework-level fact captured separately.)
 - **`TOGA_AIG.Customers.emailAddress` is `varchar(255)`** (V1 legacy, latin1_swedish_ci) — wide
   enough to hold several `'; '`-joined emails, so TRUE-79401 needed **no** schema/dbchanges migration
-  (the earlier fear that it was ~VARCHAR(55) was wrong). `TOGA_AIG` is the 1.0 legacy DB;
+  (the earlier fear that it was ~VARCHAR(55) was wrong) — but **it is a real ceiling: ~6–7
+  business-length addresses** (measured: 3 = 145 chars, 5 = 243 fit; 8 = 390, 10 = 489 overflow).
+  The 2.0 collection is unbounded; this column is not. See *Storage is bounded* above. `TOGA_AIG` is the 1.0 legacy DB;
   `Client_Aig` is the 2.0 prod tenant.
 - **The multi-email path is not yet exercised in prod data (TRUE-79401)** — as of 2026-07-28 all 20
   `Client_Aig.ContactEmailAddresses` rows are one-per-contact. The *payload-shape* question that
@@ -280,10 +316,48 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
   was ~VARCHAR(55)" traces to a garbled transcript line — "needs to fifty-five… maybe we should
   change it to a long"; the column is `varchar(255)`. Closed.)
 - **PHP 7.2** target (prod worker/library) — no arrow functions, typed properties, `??=`, `match`.
-  Lint with `C:\xampp7\php\php.exe -l`.
+  Lint with your **PHP 7.2 CLI** (`php -l <file>`); do not lint 1.0 code with a PHP 8 binary. (The
+  per-machine location of each PHP CLI is a developer-local detail and is deliberately not recorded
+  here.)
+- **This logic IS testable without a database — and there is a harness.**
+  `App_Database::sqlEscape()` needs **no DB connection** (pure `str_replace`), so the email
+  transform can be exercised statically. The TRUE-79401 transform is inlined in the DB-writing
+  `private static syncContactToToga1Customer()`, so the harness **mirrors** it and guards against
+  drift by asserting the production statements verbatim — see
+  [static no-DB regression harness](../../test/features/static-no-db-regression-harness.md). **If
+  you edit those 5 statements, the harness will refuse to report until it is updated.** The clean
+  fix if you are already in there: extract the transform to a `public static` helper so the mirror
+  disappears.
+- **Pre-existing (low severity, out of scope): a raw-vs-escaped comparison causes a redundant
+  UPDATE every sync.** At the update path (~line 8584) `syncContactToToga1Customer` compares
+  `$existingCustomer['emailAddress'] !== $emailAddress` — the DB value from
+  `App_Database::fetchRow()` is **unescaped**, while `$emailAddress` has already been through
+  `App_Database::sqlEscape()`. For any value containing `'`, `"` or `\` the two can **never** compare
+  equal, so that column is rewritten on **every** run. Same pattern applies to `businessName` and
+  `phoneNumber` just above. **Predates TRUE-79401**, is a redundant write (not data loss or
+  corruption), and was deliberately left out of that ticket's scope — recorded here so a future
+  reader knows it is known.
 
 ## Change history
 
+- 2026-08-03 (later pass) — TRUE-79401 **static regression harness + one correction.** BUILT a
+  no-DB PHP harness (`test/@Mark/AIG/test_multi_email.php`, 12 cases, PHP 7.2.33, `php -l` clean)
+  that feeds mocked `/contacts` fragments through the email transform and asserts the delimited
+  string; it **mirrors** the transform (inlined in the DB-writing private method) and **guards
+  against drift** by asserting the 5 production statements verbatim, plus parses
+  `CUSTOMER_EMAIL_DELIMITER` from source — technique documented in
+  [static no-DB regression harness](../../test/features/static-no-db-regression-harness.md).
+  **CORRECTION (supersedes the earlier same-day entry):** a bare-string collection does **not**
+  blank/vanish the addresses — it **silently degrades to primary-only**, byte-identical to correct
+  single-email output, so the wrong shape is indistinguishable from the feature being disabled;
+  child row counts in `Client_Aig.ContactEmailAddresses` are the only signal. Also recorded: the
+  omitted-primary sub-case (repeat the primary in the array); the **`varchar(255)` ceiling of ~6–7
+  business-length addresses** (so "send as many as you like" is false at the 1.0 layer, qualifying
+  the earlier pitch); the pre-existing raw-vs-escaped comparison causing a redundant UPDATE every
+  sync (~line 8584, out of scope); genericized the lint instruction (was a non-existent absolute
+  `C:\xampp7\...` path); and **verified the TRUE-79401 branch is fully merged with `_production`
+  with its patch intact at +17/−2 under ~404 insertions of other tickets' merge noise** (deploy to
+  the prod worker still unverified). (mhammontree)
 - 2026-08-03 — TRUE-79401 **payload shape RESOLVED** (review/no-code session; sources: AIG's
   field-mapping spreadsheet, the 2026-05-01 Teams meeting, the 2026-05-04 AIG email). Both
   `UserDefined3` and `UserDefined4` map to the **same** nested

package/knowledge/1.0/apps/test/INDEX.md

@@ -9,6 +9,7 @@
 | [Developer Generators (password, UUID)](features/dev-generators.md) | Two tiny **1.0 `App_` framework** convenience scripts for everyday developer needs. | test/team/generate_password.php, test/team/uuid.php |
 | [Forecast vs NetSuite Discrepancy Analysis](features/forecast-netsuite-discrepancy-analysis.md) | `team/forecast-netsuite/discrepancy_analysis.php` detects discrepancies between our **Forecast database** and **NetSuite** (the source of truth for all sales da | test/team/forecast-netsuite/discrepancy_analysis.php |
 | [@goagilant.com → @togatech.com Email-Domain Migration (1.0 + 2.0)](features/goagilant-to-togatech-email-migration.md) | Reference + technique for migrating the company email domain `@goagilant.com` → `@togatech.com` across **both** platforms. | migrate_goagilant_to_togatech_2026-06-26.sql, migrate_goagilant_to_togatech_LEGACY_2026-06-26.sql |
+| [Static (no-DB) Regression Harness for 1.0 Logic + Source Drift Guard](features/static-no-db-regression-harness.md) | 1.0 has **no PHPUnit**, and most of its business logic sits inside methods that also write SQL, so "just call it" means standing up a client database. | test/@Mark/AIG/test_multi_email.php, library/app/database.php, library/app/api/toga2.php |
 | [TableView Builder (2.0 TableViews SQL generator)](features/tableview-builder.md) | `team/tableViewBuilder/` generates SQL `INSERT` statements for the **2.0 `TableViews`**, `TableViewFields`, and `TableViewJoins` tables from a plain SQL `SELECT | test/team/tableViewBuilder/TableViewGenerator.php, test/team/tableViewBuilder/index.php, test/team/tableViewBuilder/Instructions.md |
 | [Talos Knowledge Base Pipeline (Uploader + Processor)](features/talos-kb-pipeline.md) | `team/talos/` holds the two-script web tooling that feeds the **TOGa Talos** (TOGa IQ) AI knowledge bases. | test/team/talos/kb_uploader.php, test/team/talos/kb_processor.php, test/team/talos/kb_processor.ini |
 | [TOGa 2.0 Client Onboarding SQL Generator](features/toga2-client-onboarding-sql.md) | > **Superseded by the browser wizard.** The generation logic here was extracted into the reusable > `OnboardingSqlGenerator` class and wrapped in a local browse | test/team/generate_toga2_onboarding_sql.php |

package/knowledge/1.0/apps/test/features/static-no-db-regression-harness.md

@@ -0,0 +1,100 @@
+---
+title: Static (no-DB) Regression Harness for 1.0 Logic + Source Drift Guard
+framework: "1.0"
+repo: test
+project: Test
+client: shared
+type: feature
+status: active
+updated: 2026-08-03
+owners: ["mhammontree"]
+files:
+  - test/@Mark/AIG/test_multi_email.php
+  - library/app/database.php
+  - library/app/api/toga2.php
+related:
+  - ../architecture.md
+  - ../../library/features/toga2-api-client-and-bridge.md
+  - ../../library/architecture.md
+---
+
+## Summary
+
+1.0 has **no PHPUnit**, and most of its business logic sits inside methods that also write SQL,
+so "just call it" means standing up a client database. This doc records the technique that makes
+a large class of 1.0 logic testable **statically — no DB connection, no framework bootstrap** —
+plus the **source drift guard** that keeps such a test honest when the logic under test cannot
+actually be invoked.
+
+First built for TRUE-79401 (`test/@Mark/AIG/test_multi_email.php`): 12 cases feeding mocked 2.0
+`/contacts` payload fragments through the multi-email transform and asserting the delimited
+string that would be written to `TOGA_AIG.Customers.emailAddress`. Runs on PHP 7.2.33, `php -l`
+clean, no database.
+
+## Key enabler: `App_Database::sqlEscape()` needs NO database connection
+
+This is the fact that unlocks static 1.0 testing and it is documented nowhere else:
+
+- `App_Database::sqlEscape()` delegates to `App_Database::mysqlRealEscapeString()`, which is a
+  **pure `str_replace`** over `\`, `\x00`, `\n`, `\r`, `'`, `"`, `\x1a`. The
+  `mysqli_real_escape_string` implementation is **commented out** in the source.
+- So it needs **no mysqli link and no `App_Registry` lookup**.
+- `library/app/database.php` declares `abstract class App_Database` with **no `extends`** and no
+  parse-time dependencies, so a test can `require_once` that one file alone.
+
+Consequence: **any 1.0 logic whose only framework dependency is escaping is unit-testable
+statically.** Consequence for correctness testing too — because escaping is a pure string
+transform, a test can assert the *exact* escaped output.
+
+## How the harness is structured
+
+1. `require_once` `library/app/database.php` only (no bootstrap, no config, no DB).
+2. Build mocked payload fragments as plain `stdClass`/arrays shaped like the 2.0 API response.
+3. Run the transform (see drift guard below) and assert the resulting string.
+4. Cases cover: single address, multiple, duplicates, blank/whitespace entries, empty
+   collection (primary fallback), and wrong payload shapes.
+5. Parse `CUSTOMER_EMAIL_DELIMITER` **out of the production source** rather than hardcoding
+   `'; '`, so changing the constant does not silently invalidate the expectations.
+
+## Drift guard — for logic that cannot be called
+
+The TRUE-79401 transform is 3 lines **inlined inside `private static
+App_Api_Toga2::syncContactToToga1Customer()`**, which also writes SQL. It cannot be invoked
+without a live client DB, so the harness must **mirror** it — and a mirror silently rots.
+
+The guard: the harness **reads `library/app/api/toga2.php`**, normalizes whitespace, and asserts
+that the **5 production statements it mirrors still appear verbatim**. On any mismatch it prints
+`DRIFT DETECTED` and **refuses to report results at all** (it does not just warn — a passing
+mirror of stale code is worse than no test).
+
+This pattern is reusable for **any 1.0 pure-logic fragment buried in a DB-writing private
+method**, which is a large share of `library`.
+
+**Cleaner long-term alternative (deliberately NOT done here):** extract the transform into a
+`public static` helper so the test calls production code directly and the mirror disappears
+entirely. That was out of scope because it changes production code; prefer it when you are
+already editing the method.
+
+## Gotchas / known issues
+
+- **A mirrored test proves the mirror, not production.** The drift guard is what makes it
+  trustworthy — never ship a mirror without one.
+- **Static tests cannot validate anything the server decides.** Column truncation, collation
+  behavior, strict mode and table-name casing are all server-config dependent — a no-DB pass says
+  nothing about them. See
+  [local vs prod MySQL config parity](../../../2.0/apps/dbchanges2/workflows/local-vs-prod-mysql-config-parity.md).
+- **`@Mark/` (and any `@<name>/`) folders in `test` are per-developer.** `test` is not branched;
+  write only in your own folder and ask before touching another developer's.
+- Lint 1.0 code with your **PHP 7.2** CLI (`php -l <file>`) — the prod worker/library target is
+  7.2, so 7.4+/8.x syntax must not appear.
+
+## Change history
+
+- 2026-08-03 — Documented the static no-DB 1.0 harness technique, built for TRUE-79401
+  (`test/@Mark/AIG/test_multi_email.php`, 12 cases, PHP 7.2.33). Key enabler recorded:
+  `App_Database::sqlEscape()` is a pure `str_replace` (the `mysqli_real_escape_string` path is
+  commented out) needing **no DB link or registry**, and `library/app/database.php` can be
+  `require_once`d alone. Also recorded the **source drift guard** for logic inlined in a
+  DB-writing private method (assert the mirrored production statements appear verbatim; refuse to
+  report results on mismatch) and parsing constants out of the source instead of hardcoding them.
+  (mhammontree)

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-01
+updated: 2026-08-03
 owners: ["dfranks", "jcardinal"]
 files:
   - _underscore/Error.php
@@ -87,6 +87,28 @@ produced a different hash on every request — dedup never actually worked.
 cannot orphan a curated Issue: an admin repoints the new fingerprint at the existing Issue
 from the Tools console to merge them.
 
+### Where each exception class routes (the class you throw IS the routing decision)
+
+| Thrown class | HTTP | Sentry | `Logs.Issue` | Fingerprint / routing |
+|---|---|---|---|---|
+| `_Exception_Validation` | **400** | no | **no** | n/a — bad client input. Still leaves a full `Logs.Api` row (see [api2 request logging](../../api2/features/request-logging.md)) |
+| `_Exception_Business` | **500** | yes | **yes** | stable `issueKey` (refactor-immune) → business recipients configured in the Tools console |
+| plain global `Exception` | **500** | yes | **yes** | **trace**-based fingerprint (moves when code moves) → developer ClickUp task |
+| `_Exception` | — | — | — | **never throw it deliberately** (below) |
+
+Verified against `api2/Controller/Index.php` (≈L205-245, L369-377) and `_Error.php`
+(`captureException` ≈L222-265, `buildFingerprint` ≈L455-490) on **2026-08-03**, while TRUE-78188
+was still in flight — **re-verify against `Controller/Index.php`** rather than trusting the table
+blindly.
+
+**`_Exception` must never appear at a deliberate throw site.** Its constructor takes **five**
+required args (`errorNumber`, `errorString`, `errorFile`, `errorLine`, `trace`) because it is an
+*error-handler shape* populated by `_Error` from `set_error_handler` context — not a general
+exception. `throw new _Exception('msg')` raises an `ArgumentCountError` **before** the intended
+exception is ever constructed, so the real signal is destroyed. Jeff states this rationale in the
+`Exception/Business.php` docblock. Census in `_underscore`: 173 plain `throw new Exception` vs 14
+`_Exception`.
+
 ### `_Exception_Business` — identity immune to refactoring
 
 `_underscore/Exception/Business.php` carries a stable `issueKey` plus a `minimumUrgency` floor.
@@ -267,6 +289,12 @@ clientUserId). **Neither was built.** As built instead:
 
 ## Change history
 
+- 2026-08-03 — Added the **exception-class routing table** (`_Exception_Validation` → 400/no
+  Issue; `_Exception_Business` → 500 + `issueKey`-fingerprinted Issue to business recipients;
+  plain `Exception` → 500 + trace-fingerprinted Issue to a developer task) and recorded that
+  **`_Exception` must never be thrown deliberately** — its 5-arg error-handler constructor raises
+  `ArgumentCountError` first. Verified against `Controller/Index.php` / `_Error.php` while
+  TRUE-78188 was still in flight. (dfranks)
 - 2026-08-01 — **Decided: `Logs` cluster tables use SINGULAR names.** Renamed all six
   post-deployment (`Issues`→`Issue`, `Events`→`Event`, `IssueFingerprints`→`IssueFingerprint`,
   `IssueClickupTasks`→`IssueClickupTask`, `IssueEmailAddresses`→`IssueEmailAddress`,

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

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: architecture
 status: active
-updated: 2026-07-28
-owners: [jcardinal, bala, mhammontree]
+updated: 2026-08-03
+owners: [jcardinal, bala, mhammontree, dfranks]
 files:
   - api2/Controller/Index.php
   - api2/Component/Api/V2/V2.php
@@ -102,6 +102,12 @@ One ~2,000-line `execute()` then `processRoutePairs()`:
    `public`, `delegator`/`encrypted`. JWTs HS256, `sub` access/refresh (access 3600s,
    refresh 30d); signing secret **rotated** with current+previous accepted across the
    boundary. The JWT `id` claim carries the full identity used for ACL.
+   **`/v2/auth/oauth` credential transport:** OAuth 2.0 `client_credentials`. `client_id` +
+   `client_secret` may arrive as **HTTP Basic** *or* as POST body fields — **Basic takes
+   priority** when both are present. `scope` is **required**; `grant_type` is **optional** and
+   defaults to `client_credentials` (accepted: `client_credentials`, `password`,
+   `refresh_token`). The call mints a JWT; subsequent requests carry `Authorization: Bearer`.
+   (`api2/Component/Api/V2/V2.php` L414-460.)
 4. **Response envelope** — `{transactionId, timestamp, authority, audience, isSuccess,
    status, error, messages[], meta{}, data{}}`; `isSuccess` = 2xx status.
 5. **Transaction logging** — every request logged (to client/core Logs DB, or as a JSONL

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

@@ -135,9 +135,20 @@ anywhere — no `messages[]`, nothing in the client `Logs` or the core/writer `L
    `UserDefined3`) instead of the nested collection. The key is dropped; no child row is created.
 2. **Array of bare strings instead of array of objects.** `"contactEmailAddresses":
    ["email2@domain.com"]` instead of `[{"emailAddress": "email2@domain.com"}]`. Nothing is
-   created, and any consumer doing `array_column($list, 'emailAddress')` gets an **empty** list —
-   so a downstream sync silently falls back to the primary email and the extra addresses vanish
-   with no trace.
+   created, and any consumer doing `array_column($list, 'emailAddress')` gets an **empty** list.
+
+   **Corrected 2026-08-03 (proven by harness):** the downstream effect is **not** an empty/blanked
+   field. The empty list makes the consumer's **primary-email fallback fire**, so it stores
+   **exactly the primary address** — output that is **byte-identical to correct single-email
+   behavior**. There is therefore **no observable difference between "the partner sent the wrong
+   shape" and "the partner hasn't enabled the extra addresses yet."** That is strictly *worse* for
+   diagnosis than a blanked field would be, and it is why the child ROW COUNT is the only reliable
+   signal (see below) — the consumer's stored value cannot distinguish the two.
+
+   Related shape trap in the same family: if the partner sends extras but **omits the primary from
+   the collection**, the primary is **not re-added** — the fallback only fires on a *fully empty*
+   list — so the consumer stores the secondary/tertiary but **not** the main address. Tell partners
+   to **repeat the primary inside the array**.
 
 **Operational rules that follow:**
 
@@ -163,6 +174,15 @@ anywhere — no `messages[]`, nothing in the client `Logs` or the core/writer `L
 
 ## Change history
 
+- 2026-08-03 (later pass) — **Correction, supersedes the entry below on one point.** The bare-string
+  collection shape does **not** make the addresses "vanish"/blank the consumer's field: the empty
+  `array_column()` result makes the consumer's primary-email fallback fire, so the stored value is
+  **byte-identical to correct single-email output** and the wrong shape is **indistinguishable from
+  the feature simply not being enabled** — worse for diagnosis, and confirmation that the child row
+  count is the only reliable signal. Also added the omitted-primary sub-case (the fallback fires
+  only on a *fully empty* list, so a collection lacking the primary stores the extras **without**
+  the main address — partners should repeat the primary inside the array). Proven by the TRUE-79401
+  static harness. (mhammontree)
 - 2026-08-03 — Documented that V2 **silently ignores unrecognized payload keys and does not
   validate nested-collection element shape**: both a flat/unknown key and an array of bare strings
   (instead of an array of objects) return **HTTP 201** with the data dropped and no error logged

package/knowledge/2.0/apps/api2/features/request-logging.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-29
+updated: 2026-08-03
 owners: ["mhammontree", "dfranks"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -46,6 +46,21 @@ In `api2/Component/Api/V2/V2.php` (~L2168) every request is logged and routed:
 - There is also a **config-gated branch** (~L2166): when `_Config::api('log_filepath')` is set,
   the log entry is written to a **file** on the host instead of the DB.
 
+### A rejected request (HTTP 400) is NOT unlogged
+
+`api2/Controller/Index.php` (L369-377) handles a non-success response by **committing** the
+`DB_LOGS` and `DB_CLIENT_LOGS` transactions and rolling back **only** the business-data
+transaction. A rejection therefore still writes a **full `Client_Logs.Api` / `Core_Logs.Api`
+row** — request payload, response payload, `apiId`, `sourceIp`, `transactionId` — while the
+business row is discarded.
+
+So a 400 **is** SQL-queryable and attributable to the calling credential. What a 400 lacks is a
+`Logs.Issue` row: **no alerting, no aggregation, no owner** (see
+[Error Reporting — Issue/Event Capture](../../_underscore/features/error-reporting-issue-event.md)).
+That is the deciding factor when choosing between `_Exception_Validation` (400, logged as a
+request, no Issue) and `_Exception_Business` (500, Sentry + a routed Issue). Do **not** reach for
+`_Exception_Business` merely to "make sure the rejection is recorded" — it already is.
+
 ## Blind spots when auditing a client's API traffic
 
 Looking only at `Logs_<Client>.Api` misses four sources:
@@ -95,6 +110,11 @@ re-send.
 
 ## Change history
 
+- 2026-08-03 — Corrected a common wrong assumption: an **HTTP 400 leaves a full log row**.
+  `Controller/Index.php` L369-377 commits `DB_LOGS`/`DB_CLIENT_LOGS` and rolls back only the
+  business transaction, so rejections are queryable and attributable to the credential; what they
+  lack is a `Logs.Issue` (no alerting/owner) — the deciding factor between `_Exception_Validation`
+  and `_Exception_Business`. (dfranks)
 - 2026-07-29 — Documented (TRUE-80179) that the core/writer `Logs.Api` retains the **full original
   `requestPayload`** on failed writes, making it a **replayable backlog source** and a scope
   diagnostic: dedupe to one-per-contract with a window function on

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

@@ -5,4 +5,5 @@
 | [Database Changes (dbchanges2) Repository Architecture](architecture.md) | `dbchanges2` is the **schema-migration / SQL change-set repository** for the entire 2.0 platform. | Core/, Client/, Client_<Tenant>/, Logs/, Logs_Client/, _modules/ |
 | [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Core/2026-07-20a - Update - HideAdminNotesSectionByDefault.sql, dbchanges2/Core/2026-07-20b - Update - NotesSectionFieldElements.sql, dbchanges2/Client_Compass/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_Compass/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_Quad/2026-07-20a - NotesSectionFieldsOverride.sql, dbchanges2/Core/2026-07-20c - Update - VendorItemsToggleSurfaceSeed.sql, dbchanges2/Client_Compass/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Core/2026-07-20e - RestoreApproveDenyRowActions.sql, dbchanges2/Client_Compass/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Core/2026-07-17 - README - RUN ORDER.md, dbchanges2/Client_Compass/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Compass/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_CompassCanada/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_Quad/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Quad/2026-07-21b - SalesOrderApproveDisabledTooltipTranslation.sql, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Core/2026-07-23a - PoNumberDetailFieldValueKey.sql |
 | [2.0 New-Client Onboarding (manual process)](workflows/client-onboarding.md) | > **A local browser wizard now automates this.** Steps 2–9 below (create DBs, generate Core/API > inserts, append to `Clients_Db.txt`) — plus the dbchanges2 bla | Client/, Client_<Tenant>/, Core/, Logs_Client/ |
+| [Local vs prod MySQL config parity — why “it passed locally” is not evidence](workflows/local-vs-prod-mysql-config-parity.md) | Several migration failures that look like "prod-only bugs" are actually **per-machine MySQL server-configuration differences**. |  |
 | [Repairing non-prod metadata drift (works in prod, broken in beta/dev-sandbox)](workflows/nonprod-metadata-drift-repair.md) | Almost all 2.0 platform behavior is **metadata** — `Core.Records`/`RecordFields`, `Core.RecordScripts`, `Core.ApiPayloadInterceptors`, and per-client `Acl*` row | dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql, dbchanges2/Core/2026-07-16a - TrackingNumberSignatureTypeRecordField.sql, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql, api2/Config/beta.ini |

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

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: architecture
 status: active
-updated: 2026-07-31
+updated: 2026-08-03
 owners: [jcardinal, mhammontree, bala, ajean]
 files:
   - Core/
@@ -417,6 +417,42 @@ under the 64 MB `max_allowed_packet` default. First hit in
 `Client_Aig/2026-06-18a - TRUE-79534 AIG SaleItem codes.sql` (2,200 AIG SaleItem codes); see
 `clients/aig/features/entitlement-intake.md` → *Uploading new codes*.
 
+### Staging tables MUST pin the collation of the column they join against
+
+A `CREATE TEMPORARY TABLE` that omits an explicit `COLLATE` inherits the **connection/database
+default**, which is **not** guaranteed to match the target column. The moment the staging column
+is joined to a real column with a different collation, MySQL raises:
+
+    ERROR 1267 (HY000): Illegal mix of collations (utf8mb4_general_ci,IMPLICIT) and
+    (utf8mb4_unicode_ci,IMPLICIT) for operation '='
+
+The connection default is commonly `utf8mb4_general_ci`, while 2.0 tenant tables are **typically**
+`utf8mb4_unicode_ci` (verified for `Client_Aig.Items.partNumber`) — so the mismatch is the default
+outcome, not the exception. **Always declare the collation explicitly on every staging column that
+participates in a join**, copying it from the column being matched:
+
+```sql
+CREATE TEMPORARY TABLE _stage (
+	uuid VARCHAR(36) NOT NULL,
+	keyColumn VARCHAR(255) COLLATE utf8mb4_unicode_ci NOT NULL,  -- pinned to TargetTable.keyColumn
+	otherColumn TEXT NULL
+);
+```
+
+**This is a per-machine failure, not a per-query one.** Whether it fires depends on the server's
+own defaults, so the *same file* passes on one developer's machine and dies on another's — and on
+the production server. Measured: it ran clean on MySQL **8.0.39** and failed with 1267 on
+**8.0.44** with no change to the SQL. The same class of per-machine divergence applies to
+**`sql_mode`** (e.g. `ONLY_FULL_GROUP_BY`/strict-mode rejecting a statement that passed elsewhere),
+**`lower_case_table_names`** (table-name casing resolving locally and 404-ing on Linux), and
+**`thread_stack`** (the `UNION ALL` parse limit above triggering at different sizes).
+
+**Rule: a local pass is NOT evidence that a migration is portable.** Anything that depends on a
+server variable must be pinned **in the SQL file itself** — explicit `COLLATE`, explicit column
+casing, no reliance on a permissive `sql_mode`. Verify server-setting parity before trusting a
+local run; see the environment-parity workflow in
+`2.0/apps/_underscore/architecture.md` → *Database architecture*.
+
 ## Self-referencing DELETE — wrap the subquery in a derived table
 
 MySQL forbids a `DELETE` (or `UPDATE`) whose `WHERE` subquery reads **the same table being
@@ -511,6 +547,15 @@ defined in `2.0/apps/_underscore/architecture.md`, and its change files create/a
 tables that `_Model_*` classes map to.
 
 ## Change history
+- 2026-08-03 — **Added *Staging tables MUST pin the collation of the column they join against*.**
+  A `CREATE TEMPORARY TABLE` without an explicit `COLLATE` inherits the connection default
+  (commonly `utf8mb4_general_ci`) and dies with **error 1267 illegal mix of collations** when
+  joined to a tenant column that is typically `utf8mb4_unicode_ci` (verified for
+  `Client_Aig.Items.partNumber`). Pin the collation on every staging column used in a join.
+  Reframed as the general rule that **a local pass is not evidence of portability**: the same file
+  ran clean on MySQL 8.0.39 and failed on 8.0.44 unchanged, and the same per-machine divergence
+  applies to `sql_mode`, `lower_case_table_names`, and `thread_stack`. Anything depending on a
+  server variable must be pinned in the SQL file itself. (mhammontree)
 - 2026-07-31 — **Added *`Core.Records` / `Core.RecordFields` — the only hardcoded `id`s on the
   platform* + rule #9.** These two tables are the **only** ones platform-wide whose `id` is a
   team-maintained constant: the next available value is tracked **in the developer chat**, so a

package/knowledge/2.0/apps/dbchanges2/workflows/local-vs-prod-mysql-config-parity.md

@@ -0,0 +1,113 @@
+---
+title: "Local vs prod MySQL config parity — why “it passed locally” is not evidence"
+framework: "2.0"
+repo: dbchanges2
+project: Database Changes
+client: shared
+type: workflow
+status: active
+updated: 2026-08-03
+owners: ["mhammontree"]
+related:
+  - ../architecture.md
+  - ../workflows/nonprod-metadata-drift-repair.md
+  - ../../../clients/aig/features/entitlement-intake.md
+  - ../../../1.0/apps/test/features/static-no-db-regression-harness.md
+---
+
+## Summary
+
+Several migration failures that look like "prod-only bugs" are actually **per-machine MySQL
+server-configuration differences**. They are not version differences and not environment
+properties — prod and local are both **MySQL 8.0** — so the same SQL can pass on one developer's
+machine, fail on another's, and fail on deploy, with no code change involved.
+
+Measured 2026-08-03: **prod Core = 8.0.39**, **local Core_2 = 8.0.44**. Same engine, same major
+version.
+
+**Operating rule: a local pass is NOT evidence that a migration is safe.** Run the parity query
+below before trusting a local result, and pin anything the server would otherwise decide for you.
+
+## Parity check — run this on BOTH the target environment and locally
+
+```sql
+SELECT VERSION(), @@collation_server, @@character_set_server, @@sql_mode,
+       @@lower_case_table_names, @@thread_stack, @@max_allowed_packet;
+```
+
+Compare the two outputs before concluding anything from a local run. (Machine-specific config
+file locations and one developer's overrides are deliberately **not** recorded here — they belong
+in per-developer notes, not the shared KB.)
+
+## 1. `collation_server` — the ERROR 1267 trap is per-MACHINE, not prod-only
+
+Measured: **prod `collation_server = utf8mb4_0900_ai_ci`** (the MySQL 8 *default*); **local
+`utf8mb4_unicode_ci`** (an explicit config override on that machine).
+
+So the difference is a **config property of whichever server was left at the MySQL 8 default** —
+*not* a property of "production". Consequences:
+
+- A developer on a **stock MySQL 8** install **will** reproduce `ERROR 1267 (Illegal mix of
+  collations)` locally, and is actively misled by any doc claiming it only happens on prod.
+- A developer with the `utf8mb4_unicode_ci` override will **never** reproduce it.
+- It is **fragile**: a MySQL reinstall or a reset config file silently flips the behavior with no
+  code change.
+
+**Mitigation (unchanged, now correctly justified):** always pin
+`CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci` **explicitly** on temp/staging columns that
+will be compared to a real table column. Because the server default is per-machine, **a local
+pass proves nothing** about the deploy target. First hit on the AIG SaleItem load — see
+[AIG entitlement intake](../../../clients/aig/features/entitlement-intake.md) → *Uploading new
+codes*.
+
+## 2. `sql_mode` — an empty local mode truncates where prod throws ERROR 1406
+
+MySQL 8's default `sql_mode` includes **`STRICT_TRANS_TABLES`** and **`ONLY_FULL_GROUP_BY`**. A
+local instance configured with an **empty `sql_mode`**:
+
+- **Silently TRUNCATES** an over-length write (e.g. a >255-char value into a `varchar(255)`)
+  where a strict server raises **`ERROR 1406 Data too long`**.
+- Accepts `GROUP BY` queries that a strict (`ONLY_FULL_GROUP_BY`) server **rejects**.
+
+Directly relevant to the 1.0 multi-email work: overflow of `Customers.emailAddress` behaves
+**differently per machine** — truncate here, hard error there. See
+[the library bridge doc](../../../1.0/apps/library/features/toga2-api-client-and-bridge.md).
+
+## 3. `lower_case_table_names` — a PERMANENT Windows-local vs Linux-prod difference
+
+- Windows dev installs typically run **`lower_case_table_names=2`**; Linux prod runs **`0`**
+  (case-**sensitive** table names).
+- It **cannot be changed after the data directory is initialized** — MySQL 8 refuses to start on a
+  data-dictionary mismatch — and `0` is **not permitted on Windows at all**. This one is not
+  fixable, only worked around.
+- Consequence: SQL referencing a table with the wrong casing (e.g. `contactemailaddresses` instead
+  of `ContactEmailAddresses`) **passes locally and fails on prod.**
+
+2.0 table names are **PascalCase**, so treat exact table-name casing as something local testing
+can **never** validate. Review it by eye.
+
+## 4. `thread_stack` — a bigger local stack hides ERROR 1436 until deploy
+
+`thread_stack` is what produced the **`ERROR 1436 Thread stack overrun`** on the ~2,200-row
+`UNION ALL` in TRUE-79534. A larger local stack means a big migration **parses locally and dies on
+deploy** — the same shape as the collation trap. The fix is still structural (flat multi-row
+`VALUES` into a temp table, never a long `UNION ALL` chain); see
+[dbchanges2 architecture](../architecture.md) → *Bulk data loads*. Do not raise `thread_stack` for
+a one-off load.
+
+## Gotchas / known issues
+
+- **The common failure mode is a false negative, not a false positive.** Every item above lets bad
+  SQL pass locally. Nothing here makes good SQL fail on prod.
+- **Do not "fix" a parity gap by changing the server.** Pin collations in the SQL, keep casing
+  exact, size values to the column, and structure bulk loads to avoid parser recursion.
+
+## Change history
+
+- 2026-08-03 — Created. Established that the `ERROR 1267` temp-table collation trap is a
+  **per-machine config property, not a prod-only / version difference** (measured prod 8.0.39 with
+  `utf8mb4_0900_ai_ci`, local 8.0.44 with an explicit `utf8mb4_unicode_ci` override) — a developer
+  on a stock MySQL 8 install reproduces it locally. Added the `sql_mode` finding (empty local mode
+  silently truncates where strict prod raises `ERROR 1406`, and disables `ONLY_FULL_GROUP_BY`), the
+  permanent `lower_case_table_names` Windows-vs-Linux table-name-casing gap, the `thread_stack`
+  connection to `ERROR 1436`, and the cross-environment parity query. (mhammontree)

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

@@ -5,8 +5,8 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-08-01
-owners: [jcardinal, mhammontree]
+updated: 2026-08-03
+owners: [jcardinal, mhammontree, dfranks]
 files: []
 related:
   - ../apps/_underscore/architecture.md
@@ -573,15 +573,42 @@ $c = 'Hello ' . $world;
 
 * Always use exceptions to handle unexpected conditions.
 
-### Interceptor / model client-error rejections → throw `_Exception_Validation`, not `_Exception`
-
-A hard-block raised inside a pre/post interceptor (or model op) to reject a **bad client request**
-must throw **`_Exception_Validation`** (`_underscore/Exception/Validation.php`), which
-`api2/Controller/Index.php` (≈lines 204–222) maps to `DEFINED_MESSAGE_ERROR_BAD_REQUEST` →
-**HTTP 400** with the message carried in the response envelope (so the front end can drive a
-toaster). Throwing a plain `_Exception` yields an **HTTP 500 + stack trace** — wrong for a
-client-input rejection and an information leak. First applied: the three Rate WH hard-blocks
-(missing / invalid / duplicate service address), TRUE-79533.
+### Choosing an exception class is a ROUTING decision, not style
+
+At a deliberate throw site the class you pick determines the HTTP status, whether Sentry sees
+it, whether a `Logs.Issue` is created, how that Issue is fingerprinted, and **who gets
+notified**. Pick deliberately:
+
+| Throw this | When | HTTP | Sentry | `Logs.Issue` | Goes to |
+|---|---|---|---|---|---|
+| `_Exception_Validation` | bad **client input** — a hard-block in a pre/post interceptor or model op | **400** | no | no | the caller, via the response envelope (front end can toast it) |
+| `_Exception_Business` | a **business condition a business user can act on and a developer cannot fix** | 500 | yes | yes, keyed by a stable `issueKey` | business recipients configured in the Tools `/errors` console |
+| plain global `Exception` | a genuine **code defect / unexpected state** | 500 | yes | yes, fingerprinted by **trace** | a developer ClickUp task |
+
+`_Exception_Business`'s constructor is `(issueKey, message, minimumUrgency)`. The `issueKey` is
+the fingerprint, so the Issue's identity survives refactoring; a plain `Exception`'s
+trace-based fingerprint changes when the code moves.
+
+**A 400 is not "unlogged."** `api2/Controller/Index.php` commits the log transactions and rolls
+back only the business transaction, so a rejection still writes a full `Logs.Api` row (request
++ response payload, `apiId`, `sourceIp`, `transactionId`). What a 400 lacks is a `Logs.Issue` —
+no alerting, no aggregation, no owner. Do not upgrade a client-input rejection to
+`_Exception_Business` just to "make sure it's recorded."
+
+### NEVER `throw new _Exception(...)`
+
+`_Exception` is an **error-handler shape**, not a general exception: its constructor requires
+five arguments (`errorNumber`, `errorString`, `errorFile`, `errorLine`, `trace`) because
+`_Error` populates it from `set_error_handler` context. `throw new _Exception('msg')` raises an
+`ArgumentCountError` **before** your exception is ever constructed, destroying the real signal.
+Throwing a plain `_Exception` also yields an HTTP 500 + stack trace — wrong for a client-input
+rejection and an information leak. Census in `_underscore`: 173 plain `throw new Exception` vs
+14 `_Exception`.
+
+Sources: `_underscore/Exception.php`, `Exception/Validation.php`, `Exception/Business.php`,
+`_underscore/Error.php`, `api2/Controller/Index.php`. First applied: the three Rate WH
+hard-blocks (TRUE-79533). Taxonomy verified 2026-08-03 **while TRUE-78188 was still in flight** —
+re-verify against `Controller/Index.php` before relying on it.
 
 ### Comprehensive Error Handling
 

package/knowledge/INDEX.md

@@ -12,7 +12,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **togaview** (TOGa View) — 6 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 - **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
-- **test** (Test) — 13 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
+- **test** (Test) — 14 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 2 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
 - **tools** (Tools) — 13 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 
@@ -21,7 +21,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **_underscore** (_Underscore) _(framework core)_ — 42 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 38 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 21 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
-- **dbchanges2** (Database Changes) _(framework core)_ — 4 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
+- **dbchanges2** (Database Changes) _(framework core)_ — 5 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **toga2-view** (TOGa View Frontend) — 7 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)

package/knowledge/clients/aig/features/entitlement-intake.md

@@ -227,12 +227,15 @@ When AIG sends a new "Active SaleItemID" spreadsheet (columns `SaleItemID`, `Des
    The `TEMPORARY` table is session-scoped (safe on production, auto-dropped on disconnect
    even if the run aborts). Do **not** raise `thread_stack` on the server for a one-off load.
 5. **Pin the staging `partNumber` collation explicitly to `utf8mb4_unicode_ci`** (as shown
-   above). If you omit it, the temp column inherits the **server default**, which on the MySQL 8
-   **prod** server is `utf8mb4_0900_ai_ci` — while `Client_Aig.Items.partNumber` is
-   `utf8mb4_unicode_ci`. The anti-join's `existing.partNumber = src.partNumber` then mixes
-   collations and dies with **ERROR 1267 (Illegal mix of collations)**. It does **not** fail
-   locally (the local server default is already `utf8mb4_unicode_ci`), so this is a **prod-only**
-   failure — see the gotcha.
+   above). If you omit it, the temp column inherits the **server default**. On any server left at
+   the MySQL 8 default that is `utf8mb4_0900_ai_ci` — including **prod** — while
+   `Client_Aig.Items.partNumber` is `utf8mb4_unicode_ci`. The anti-join's
+   `existing.partNumber = src.partNumber` then mixes collations and dies with **ERROR 1267
+   (Illegal mix of collations)**. This is a **per-machine config** property, **not** a prod-only or
+   version difference (prod and local are both MySQL 8.0) — a developer on a stock MySQL 8 install
+   reproduces it locally, and a developer with a `utf8mb4_unicode_ci` override never does. So **a
+   local pass is not evidence.** See the gotcha and
+   [local vs prod MySQL config parity](../../../2.0/apps/dbchanges2/workflows/local-vs-prod-mysql-config-parity.md).
 
 ## Client variations
 
@@ -252,7 +255,12 @@ this interceptor or use this dual-purpose Items pattern.
   Both a flat/unknown key (a literal `UserDefined3`) and an array of bare strings
   (`"contactEmailAddresses": ["a@b.com"]` instead of `[{"emailAddress": "a@b.com"}]`) are accepted
   with **no error anywhere**. When verifying AIG's multi-email feed, assert **actual
-  `Client_Aig.ContactEmailAddresses` row counts** — never the HTTP status. See
+  `Client_Aig.ContactEmailAddresses` row counts** — never the HTTP status, **and (corrected
+  2026-08-03) never the 1.0 `TOGA_AIG.Customers.emailAddress` value either.** Proven by harness:
+  the bare-string shape does **not** blank the 1.0 field — `array_column()` returns an empty list,
+  the primary-email fallback fires, and the stored value is **byte-identical to correct
+  single-email output**, so "AIG sent the wrong shape" and "AIG hasn't enabled the feature yet"
+  are indistinguishable. The child row count is the **only** reliable signal. See
   [api2 nested-relationship writes](../../../2.0/apps/api2/features/nested-relationship-writes.md).
 - **A sale-item code missing from `Client_Aig.Items` currently produces an HTTP 500, not a clean
   "Missing AIG item ID."** In prod (TRUE-79534) a valid-but-unknown code made `$itemId` empty and
@@ -295,17 +303,34 @@ this interceptor or use this dual-purpose Items pattern.
   type. **Both stem from the same unguarded lookup** — `prePost` must guard an empty/failed lookup
   and return a clean "Missing AIG item ID" **before** running the fulfillment query or injecting
   anything. Not yet fixed.
-- **Staging a temp table for a `Client_Aig` load can hit ERROR 1267 on prod only.** A
-  `CREATE TEMPORARY TABLE` column with no explicit collation inherits the server default —
-  `utf8mb4_0900_ai_ci` on the MySQL 8 prod server — while `Client_Aig.Items.partNumber` is
-  `utf8mb4_unicode_ci`; the anti-join `=` then mixes collations → **ERROR 1267 (Illegal mix of
-  collations)**. It passes locally (local default already `utf8mb4_unicode_ci`), so it is a
-  **prod-only** trap. Always pin the staging `partNumber` column
-  `CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci` (see *Uploading new codes* step 5). This is a
-  general dbchanges2 temp-table-staging rule, not AIG-specific.
+- **Staging a temp table for a `Client_Aig` load can hit ERROR 1267 — on whichever server is left
+  at the MySQL 8 default collation (a PER-MACHINE config trap, not "prod-only").** A
+  `CREATE TEMPORARY TABLE` column with no explicit collation inherits `@@collation_server`, which
+  is `utf8mb4_0900_ai_ci` by default on MySQL 8 (prod is exactly this) — while
+  `Client_Aig.Items.partNumber` is `utf8mb4_unicode_ci`; the anti-join `=` then mixes collations →
+  **ERROR 1267 (Illegal mix of collations)**. Measured 2026-08-03: prod Core **8.0.39 /
+  `utf8mb4_0900_ai_ci`**, local Core_2 **8.0.44 / `utf8mb4_unicode_ci` (an explicit override)** —
+  same engine, same major version, so this was **never** a version or environment difference. A
+  developer on a stock MySQL 8 install **will** reproduce it locally; one with the override never
+  will; a MySQL reinstall silently flips it. Always pin the staging `partNumber` column
+  `CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci` (see *Uploading new codes* step 5) **and treat
+  a local pass as no evidence at all** — see
+  [local vs prod MySQL config parity](../../../2.0/apps/dbchanges2/workflows/local-vs-prod-mysql-config-parity.md).
+  This is a general dbchanges2 temp-table-staging rule, not AIG-specific.
 
 ## Change history
 
+- 2026-08-03 (later pass) — **Two corrections.** (1) The `ERROR 1267` temp-table collation trap is a
+  **per-machine server-config property, not a "prod-only" / version difference**: measured prod Core
+  8.0.39 with the MySQL 8 default `utf8mb4_0900_ai_ci` vs local Core_2 8.0.44 with an explicit
+  `utf8mb4_unicode_ci` override. The earlier reasoning ("the local server default is already
+  `utf8mb4_unicode_ci`") was wrong even though the mitigation was right — a developer on a stock
+  MySQL 8 install reproduces it locally, so **a local pass is not evidence.** New doc:
+  [local vs prod MySQL config parity](../../../2.0/apps/dbchanges2/workflows/local-vs-prod-mysql-config-parity.md).
+  (2) The wrong-shaped-payload gotcha overstated the symptom: an array of **bare strings** does
+  **not** blank the 1.0 email field — it **silently degrades to primary-only**, producing output
+  byte-identical to correct single-email behavior, so it is undetectable from the stored value.
+  `Client_Aig.ContactEmailAddresses` row counts remain the only reliable signal. (mhammontree)
 - 2026-08-03 — Review-only session (no code changed). **Business Unit (`UserDefined2`) is answered
   and dropped**: AIG (2026-05-04) needs nothing returned — it is theirs, from the sale, for **sales**
   invoicing (not claims invoicing); we asked them to omit it from the API call and **no invoice-file

package/knowledge/clients/compass-usa/features/mits-po-to-so-item-linking.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-07-13
-owners: ["jcardinal", "rgirish"]
+updated: 2026-08-03
+owners: ["jcardinal", "rgirish", "dfranks"]
 files:
   - _underscore/Model/Compass/PurchaseOrder.php
   - worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php
@@ -29,6 +29,56 @@ production data-integrity bug.
 - USA/Canada subclasses (`Model/Compass/Usa|Canada/PurchaseOrder.php`) are empty and inherit
   this behavior — edit the parent.
 
+## Who actually calls `POST /v2/purchase-orders` (MITS is NOT the only caller)
+
+`/v2/purchase-orders` for Compass is a **shared endpoint with two unrelated inbound channels**,
+distinguished in `Core.ClientApiIdentities` (clientId 2). **The channels are told apart by the
+FIELD NAME, not by whether a MITS SO is present at all:**
+
+| Identity | Channel | SO field sent | Values | `purchaseOrderItems` |
+|---|---|---|---|---|
+| `153531108` | MITS | **`mitsSalesOrder`** (unprefixed) | only `SA…` or `MR…` | always present |
+| `COMPASS-CXML` | cXML / EDI | **`c_mitsSalesOrder`** (`c_`-prefixed) | numeric, e.g. `472981379001` | present |
+| `COMPASS-CXML` | cXML / EDI | **neither field** | — | often **absent entirely** |
+
+Measured over 60 days of inbound `POST /v2/purchase-orders` (`Logs_Compass.Api`):
+- **MITS — 4,547 posts, 100% carry the unprefixed `mitsSalesOrder`**; `SA` 2,928, `MR` 1,619.
+  Never `MA`, never any other prefix. **No `SA` value has ever been sent by a non-MITS caller.**
+- **COMPASS-CXML — 2,697 posts**: 2,455 carry `c_mitsSalesOrder`, and **242 carry neither field**.
+  In a 30-day slice: 1,508 `c_mitsSalesOrder` posts all had items; **136 posts had neither field
+  and no `purchaseOrderItems` key** — the legitimate header-first EDI POs.
+- Compass **Canada** posts under a **separate identity (`409531`)**, so never hardcode an
+  identity id.
+
+**Consequences for any validation added to this endpoint:**
+- **The unprefixed `mitsSalesOrder` is the MITS marker** — not the identity id, and not the
+  `SA`/`MR` prefix. Supporting evidence: `prePost` reads `$payload->mitsSalesOrder`; the only
+  `c_mitsSalesOrder` occurrence in the codebase is the model field declaration at
+  `_underscore/Model/Compass/PurchaseOrder.php:18`; and `Core.ApiPayloadInterceptors` has **no
+  rows for `recordId = 17`** (the `purchase-orders` record), so nothing rewrites field names in
+  flight.
+- A "reject purchase orders with zero line items" rule keyed on the **unprefixed** field cannot
+  touch the 136 item-less EDI posts — they carry neither field. Gating on **item count alone**
+  would reject all of them.
+- **`MA` orders never arrive from MITS.** Compass creates them manually; they go to ODP, reach us
+  over EDI, and land on an exception report for manual NetSuite entry. (An earlier belief that MA
+  is a third MITS prefix to filter on is wrong.)
+
+> **⚠ Querying trap — a substring match on `mitsSalesOrder` conflates the two callers**, because
+> `c_mitsSalesOrder` *contains* it. Anyone characterising this traffic from `Logs_Compass.Api`
+> must match the **exact key**; a pattern like `"mitsSalesOrder":"` also silently misses the
+> prefixed form, which is how this session first reached the wrong conclusion that cXML never
+> sends an SO reference. Second trap: payloads appear **both minified**
+> (`"mitsSalesOrder":"MR…"`) **and pretty-printed** (`"mitsSalesOrder": "MR…"`, space after the
+> colon), so a naive pattern under-counts a second way.
+
+> **OPEN / UNVERIFIED:** it is **not** confirmed whether the 2.0 framework strips the `c_` prefix
+> when populating `$payload` for an interceptor. If it does, cXML requests carrying
+> `c_mitsSalesOrder` would also enter a guard keyed on `$payload->mitsSalesOrder`. Harmless while
+> those posts all carry items, but a future item-less cXML post carrying `c_mitsSalesOrder` would
+> then be wrongly rejected. This **cannot be settled from logs** — it needs a dev-environment
+> check.
+
 ## How it works
 - **SA orders (normal):** each inbound PO item carries `createdFromSalesOrderItem.lineNumber`
   (the MITS line, which includes configuration-line offsets). `prePost` remaps it to the real
@@ -50,6 +100,17 @@ production data-integrity bug.
   because SA/MR originate in Compass (their Compass SO+items pre-exist) whereas MA is
   ODP-originated, so nothing else would populate it.
 
+### MR and SA consume PO line items differently (asymmetry inside one method)
+- **MR** — `handleMrOrder` (≈L54-57) **silently skips** any item whose
+  `vendorItem->item->partNumber` is empty while building `salesOrderItems`. So an MR PO whose
+  lines *all* lack a `partNumber` passes a naive `count($payload->purchaseOrderItems) > 0` check
+  and still creates an **empty Sales Order**. A "usable item" filter for MR must therefore test
+  `partNumber`, not array length.
+- **SA** — items are linked via `createdFromSalesOrderItem` →
+  `salesOrderItemPurchaseOrderItems`, and the quantity cross-check (≈L318-324) explicitly
+  `continue`s past `partNumber`-less lines rather than discarding them. Applying the MR
+  `partNumber` filter to SA would **reject valid orders**.
+
 ## Data model
 - `SalesOrderItems_PurchaseOrderItems` (`Client_Compass`): `uuid`, `salesOrderItemId`,
   `purchaseOrderItemId`. One row per (SO item, PO item) the PO fulfills.
@@ -59,6 +120,15 @@ production data-integrity bug.
 USA and Canada share the parent handler unchanged.
 
 ## Gotchas / known issues
+- **SQL injection in `prePost` (OPEN as of 2026-08-03).** `_underscore/Model/Compass/PurchaseOrder.php`
+  **L232** interpolates the raw client payload straight into SQL:
+  `WHERE SalesOrders.number LIKE '{$payload->mitsSalesOrder}'` — no escape, no cast. The **same
+  value is escaped at L301**, so the file is internally inconsistent and the correct pattern is
+  already present. Fix with `_Database::escape()` per the 2.0 back-end standard. Reachable only by
+  a caller holding valid Compass API credentials (OAuth2 `client_credentials`), so it is **not**
+  anonymous or internet-facing — normal priority, not an emergency. Separately, five sites in this
+  file (L148, L301, L461, L462, L471) use **`addslashes()`** where the standard requires
+  `_Database::escape()`.
 - **Spurious cross-part links from the `postPost` lineNumber join (fixed 2026-06-11).** The
   `postPost` link pass matched `SalesOrderItems.lineNumber = PurchaseOrderItems.lineNumber`
   for *all* orders. For SA orders that is wrong: PO line numbers are PO-local, so whenever an
@@ -137,6 +207,16 @@ USA and Canada share the parent handler unchanged.
   need item backfill from the sibling ODP SO first).
 
 ## Change history
+- 2026-08-03 — Documented that `/v2/purchase-orders` has **two** Compass inbound channels (MITS
+  `153531108` vs `COMPASS-CXML`; Canada is a third identity `409531`), told apart by **field
+  name**: unprefixed `mitsSalesOrder` = MITS, `c_mitsSalesOrder` = cXML, neither = the item-less
+  header-first EDI POs. So a zero-item rejection keyed on the unprefixed field is safe, while
+  gating on item count alone is not. Recorded the substring/pretty-print querying traps that
+  conflate the two callers, and left open whether the framework strips the `c_` prefix for
+  interceptor payloads. Also recorded the MR-vs-SA `partNumber` item-consumption
+  asymmetry (MR silently skips `partNumber`-less lines → empty SO despite `count() > 0`) and an
+  open SQL-injection at L232 plus five `addslashes()` sites. Corrects the earlier belief that
+  `MA` arrives from MITS. (dfranks)
 - 2026-07-13 — Fixed empty MA orders: the 3a ODP-PO-import cron's new-SO branch now builds
   `salesOrderItems` from the 850 PO items (the MA back-linking block excludes MA by design).
   Forward-only; 192 historical empties still need item backfill. (rgirish)

package/package.json

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