toga-ai 1.0.590 → 1.0.592

package/knowledge/1.0/apps/library/features/error-capture-1-0.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-04
+updated: 2026-08-17
 owners: ["jcardinal", "mhammontree"]
 files:
   - library/app/error/capture.php
@@ -177,6 +177,15 @@ exists in `api2`/`worker2`. So 1.0 reads the AL1 container config at
 
 ## Gotchas / known issues
 
+- **⚠ A grouped `Logs.Issue` row can show a STALE error id — read the live api2 transaction log for
+  the current error.** Two facts combine to mislead: (1) `Event.errorMessage` is **`varchar(255)`**,
+  so a long API response is **truncated** — often before the trailing error id; and (2)
+  `Logs.Issue.subject` / `Issue.errorMessage` hold the **first-occurrence** text, so a long-lived
+  issue keeps showing the error id from whenever it was first seen even after the per-call error has
+  changed. Observed 2026-08-17: issue `3H` still displayed `EO-1` / `3G-6` (the original
+  undefined-method fatal) while the current per-call failure was actually `EV-11` (an FK 1451 on a
+  DELETE). **To see what is failing *now*, read the live api2 transaction log
+  (`Logs_<client>.Api.responsePayload`) for the specific call — not the grouped `Issue` row.**
 - **Any PHP warning inside capture code would kill the request.** 1.0's
   `App_Error::handleError()` routes **every** PHP warning into `handleException()`, which renders
   the red box and calls `exit()` — so a single warning raised while capturing (an unreachable IMDS
@@ -220,6 +229,12 @@ exists in `api2`/`worker2`. So 1.0 reads the AL1 container config at
 
 ## Change history
 
+- 2026-08-17 — Recorded a diagnostic trap: a grouped `Logs.Issue` row can show a **stale error id**
+  because `Event.errorMessage` is `varchar(255)` (truncates a long API response, often before the
+  error id) and `Issue.subject`/`errorMessage` keep the **first-occurrence** text — observed issue
+  `3H` still showing `EO-1`/`3G-6` while the live per-call error was `EV-11` (FK 1451). Read the live
+  `Logs_<client>.Api.responsePayload` for the actual current error. Surfaced diagnosing the Compass
+  USA NetSuite SO sync freeze. (jcardinal)
 - 2026-08-05 — Recorded the legacy `DELETE_DOA_PRE-SENTRY_error.php` handler leaking the full
   config array (prod DB / SES / NetSuite / Payeezy / SSL Store credentials + ticket PII) on a
   live towfoundation.togaview.com error page, meaning that host evaluates as dev mode in

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-10
+updated: 2026-08-17
 owners: [jcardinal, mhammontree, bala]
 files:
   - library/app/api/toga2.php
@@ -328,6 +328,16 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
   **and** the consuming code. (The general 2.0-side metadata behavior — reverse relations resolved via
   the child model's `FOREIGNKEY_MODEL` and named as the camelCase plural of the child model — is a
   framework-level fact captured separately.)
+- **⚠ Depth alone does NOT return every reverse-hasMany collection — `GET /sales-orders` at depth 4
+  omits `itemFulfillmentItems` and `invoiceItems`.** Verified 2026-08-17 against prod
+  `Logs_Compass.Api` responses (no fields whitelist): a depth-4 sales-order GET returns
+  `salesOrderItems` and the **PO-link bridge** collections
+  (`salesOrderItemPurchaseOrderItems`, `purchaseOrderItemSalesOrderItems`) but **not**
+  `itemFulfillmentItems` or `invoiceItems`. So any importer code that guards on
+  `$salesOrderItem->itemFulfillmentItems` / `->invoiceItems` from that GET is a **silent no-op** —
+  same reverse-hasMany trap as above, now with a concrete consequence: the NetSuite SO renumber fix
+  keys off a recorded "could-not-delete" set instead of trusting those collections (see
+  [NetSuite → TOGa Supply per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md)).
 - **`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) — but **it is a real ceiling: ~6–7
@@ -386,6 +396,13 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
 
 ## Change history
 
+- 2026-08-17 — Recorded that **depth-4 `GET /sales-orders` omits the `itemFulfillmentItems` and
+  `invoiceItems` reverse-hasMany collections** (it does return `salesOrderItems` and the PO-link
+  bridges), verified against prod `Logs_Compass.Api` — so code guarding on those collections from
+  that GET is a silent no-op, reinforcing the reverse-hasMany-fields trap. Surfaced fixing the
+  NetSuite SO renumber freeze (Compass USA), which now keys off a recorded "could-not-delete" set;
+  see [NetSuite → TOGa Supply per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md).
+  (jcardinal)
 - 2026-08-12 — Recorded the **`send()` return contract**: it always returns a response carrying
   `isSuccess` (early-returns on true, falls through to `return $response` on false, throws when the
   property is absent), so `empty($response->isSuccess)` is a safe failure check on anything it

package/knowledge/1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-12
+updated: 2026-08-17
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -87,13 +87,28 @@ its IDLE write. **There is no timeout, memory cap, or resource limit anywhere in
 never *tune the window size down*. (Corollary: a window that has grown back to the cap is positive
 evidence the section is completing.)
 
-### ⚠ A per-record API failure does NOT stop the cursor — the record is skipped forever
-
-The cursor write (`LAST_SYNC_DATETIME_*`) and `finishModeIteration()` both run **unconditionally
-after** the record loop. A record that throws mid-loop is captured to Sentry and **stepped over**,
-while the section still reports success and advances the cursor past its window. So
-**"section IDLE + cursor advancing" is not proof of a complete import** — it only proves the run
-didn't die.
+### ⚠ Per-record isolation is SECTION-SPECIFIC — and SALES_ORDERS has NONE (corrected 2026-08-17)
+
+Whether a bad record is "stepped over" or freezes the section depends entirely on whether **that
+section's** record loop wraps the `sync*FromNetsuite()` call in a per-record `try/catch`. It is not
+uniform across the six sections, and the earlier blanket claim here ("a per-record failure does not
+stop the cursor — the record is skipped forever") is **false for the SALES_ORDERS section**.
+
+- **Where a section DOES isolate per record:** the cursor write (`LAST_SYNC_DATETIME_*`) and
+  `finishModeIteration()` run after the loop, so a caught record is skipped and the section still
+  reports IDLE and advances. There, **"section IDLE + cursor advancing" is not proof of a complete
+  import** — it only proves the run didn't die (recovery = rewind the cursor; re-import is
+  idempotent).
+- **⚠ SALES_ORDERS has NO per-record `try/catch`.** The `SALES_ORDERS` foreach in
+  `common_sync_togasupply.php` (~L637-673) calls `App_Api_Toga2::syncSalesOrderFromNetsuite()`
+  **bare**. `send()` throws on any non-success by default, so **one poison order throws, propagates,
+  and aborts the whole section BEFORE** the cursor PUT + `finishModeIteration()`. The mode stays
+  `1-RUNNING`, the watermark freezes, the window shrinks ÷3 each run, and the **same** order is
+  re-tried and re-throws every 5 minutes — a permanent freeze, not a skip. So a stuck
+  `SALES_ORDERS` at `1-RUNNING` with a days-frozen watermark means **it is throwing on a specific
+  order** (go read the live api2 transaction log for that client — see the poison-order gotcha
+  below). The "shrinking window is a bug signal" rule still holds; the "record is stepped over"
+  corollary does **not** for this section.
 
 Proven concretely on Elite: sales order **169441** (NetSuite internal id 4624062, trandate
 2024-04-15, customer PO `BEGGS/04152024/…`) was simply absent from `Client_Elite.SalesOrders`
@@ -361,9 +376,46 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
   a new line is actually created. Full root cause, the prod cleanup migration, and the
   deploy-fix-before-cleanup sequencing live in the
   [Compass ODP Duplicate PO-Line Cleanup](../../../clients/compass-usa/workflows/odp-duplicate-po-line-cleanup.md).
+- **⚠ A single un-deletable renumbered line could freeze the entire SALES_ORDERS section (fixed
+  2026-08-17).** When NetSuite renumbers a line, `syncSalesOrderFromNetsuite` renumbers by
+  **DELETE `/sales-order-items/{uuid}` then re-create in the per-item loop**. Its "pinned row" guard
+  only skipped rows carrying `itemFulfillmentItems` / `salesOrderItemPurchaseOrderItems` /
+  `purchaseOrderItemSalesOrderItems`; an **INVOICED** line
+  (`InvoiceItems.salesOrderItemId`, `ON DELETE RESTRICT`) was **not** guarded, so the DELETE failed
+  with MySQL **1451** → api2 **EV-11** 400, and — because the SALES_ORDERS loop has no per-record
+  `try/catch` (see the corrected gotcha above) — the throw aborted the section, freezing Compass USA
+  for ~5 days (`NETSUITE_EXECUTION_MODE_SALES_ORDERS='1-RUNNING'`, watermark stuck at
+  `2026-08-12 06:13:26`) while it re-tried the same poison order every run (SO **7447** /
+  `SalesOrderItem` 47828, invoiced by `InvoiceItem` 25515). **Fix (library-only, PHP 7.2-safe, no
+  signature changes)** in `syncSalesOrderFromNetsuite`: (1) the renumber-DELETE now passes
+  `$throwExceptionOnApiError=false`, checks `empty($resp->isSuccess)`, and records any row it cannot
+  delete in a new `$pinnedRenumberLineUniqueKeys` set (keyed by `c_netsuiteLineUniqueKey`); (2) the
+  per-item PUT loop treats a row in that set as **pinned** — it keeps its current `lineNumber` (no
+  `UNIQUE(salesOrderId,lineNumber)` collision) and its PUT is made non-throwing + `error_log` **for
+  pinned rows only** (normal rows keep throw-on-error so real failures still surface); (3) the
+  trailing "remove dropped items" DELETE now skips `invoiceItems` and checks `isSuccess`. Net: **no
+  single order can freeze the section again regardless of which `RESTRICT` child blocks a delete**;
+  the invoiced line simply stays at its existing `lineNumber` (a documented unresolvable
+  NetSuite-vs-invoiced case). Deploy `library` only — no SQL, no other repos — then the section
+  completes, mode flips IDLE, and the backlog backfills idempotently. Note the collection guard added
+  for `invoiceItems` is **best-effort only**: depth-4 `GET /sales-orders` does **not** return the
+  `itemFulfillmentItems` or `invoiceItems` reverse-hasMany collections (only the PO-link bridges), so
+  the fix keys off the recorded "could-not-delete" set rather than trusting those collections — see
+  [App_Api_Toga2 client & bridge](../../library/features/toga2-api-client-and-bridge.md).
 
 ## Change history
 
+- 2026-08-17 — Fixed a Compass USA ~5-day SALES_ORDERS freeze: an **invoiced** line that NetSuite
+  renumbered could not be DELETEd (FK `InvoiceItems.salesOrderItemId` `RESTRICT` → MySQL 1451 →
+  api2 EV-11), and because the SALES_ORDERS loop has **no per-record `try/catch`** the throw aborted
+  the whole section (mode stuck `1-RUNNING`, watermark frozen, poison order SO 7447 re-tried every
+  run). `syncSalesOrderFromNetsuite` now makes the renumber-DELETE non-throwing, records
+  un-deletable rows in a `$pinnedRenumberLineUniqueKeys` set, and keeps a pinned row at its existing
+  `lineNumber` with a non-throwing PUT (normal rows still throw on error); the trailing dropped-item
+  DELETE now skips `invoiceItems` and checks `isSuccess`. **Corrected** the prior gotcha that claimed
+  a per-record failure never stops the cursor — that is **section-specific and false for
+  SALES_ORDERS**, which has no per-record isolation. Library-only deploy; no SQL/other repos.
+  Diagnosis touched worker/api2/_underscore (read-only). (jcardinal)
 - 2026-08-12 — TRUE-80499 (Elite onboarding, shared-engine work). **Fixed** the sparse-client
   `TypeError`: the two per-client item lookups are now initialised at
   `common_sync_togasupply.php:74-75` instead of only inside the items loop, so a client whose items

package/knowledge/2.0/apps/_underscore/features/per-client-database-connections.md

@@ -178,41 +178,47 @@ here — they live in `Config/*.ini`.)
   (`db_logs`) — the laptop trap there is documented separately in the worker NetSuite bootstrap
   notes.
 
-## ⚠ OPEN QUESTION — does the alias-keyed `$_modelCache` leak across tenants? (UNPROVEN)
+## WITHDRAWN — the "alias-keyed `$_modelCache` cross-tenant leak" hypothesis (2026-08-17)
 
-**Do not repeat this as an established leak, and do not dismiss it either.** It needs a focused
-security review. Observed 2026-08-17 (TRUE-80562):
+**There is no known cross-tenant leak. Do not cite this as a security concern.** An earlier entry in
+this doc (same day, TRUE-80562) raised an *unproven* hypothesis that `_Database::$_modelCache`,
+being keyed by the shared alias `'Client'`, was emitting one tenant's `c_` columns on another
+tenant's `INSERT`. **That is not what happened.** The trigger was an AIG `Units` write failing MySQL
+1054 on six `c_` columns; the real cause was a **missing migration on beta**, not a cache collision:
 
-An **AIG** `POST /v2/entitlements` carrying nested `entitlementUnits` emitted an
-`INSERT INTO Units` containing `c_itemDescription`, `c_lastModified`, `c_chargingBrick`,
-`c_deviceStatus`, `c_chargingCable`, `c_grade` → **MySQL 1054**, surfaced as EV-12 with a
-`modelSaveError`.
+- `dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql` adds all six columns
+  (`c_itemDescription`, `c_lastModified`, `c_chargingBrick`, `c_deviceStatus`, `c_chargingCable`,
+  `c_grade`) **and** their `CustomRecordFields` rows to every client whose `_modules.txt` lists
+  `netsuite`. **`Client_Aig/_modules.txt` contains exactly `netsuite`** — AIG is opted in, so those
+  are **AIG's own fields**, not another tenant's.
+- **Prod `Client_Aig.Units` has all 7 custom columns.** Beta simply never ran that module file — the
+  same execution gap as `Entitlements.serviceAddressId`. After the module migration was run manually
+  on beta `Client_Aig`, `Units` gained all 7 columns and the nested unit write succeeded.
 
-**Verified facts:**
+**Methodology lesson — why the wrong conclusion was reached.** The model-class comparison that
+produced the leak hypothesis was made against the **local `_underscore` checkout, which was on branch
+`TRUE-80282`, while beta deploys `_sandbox-dev`.** Comparing beta *runtime* behavior against a local
+checkout on a different branch is **not evidence**. api2's architecture doc already warns that
+`_underscore` is cloned at build time from a moving branch
+([environment-variable-drives-underscore-branch](../../api2/features/environment-variable-drives-underscore-branch.md));
+this is that hazard biting in practice. Before attributing a runtime field list to a model class,
+confirm which branch the environment actually built from.
 
-- `Client_Aig.Units` has **only** `c_netsuiteInternalInventoryAssignmentId`, and
-  `Client_Aig.CustomRecordFields` declares only that one field for `Units` (recordId 31) — AIG's
-  **schema and metadata agree**.
-- Those six columns exist **only** in `Client_Adyen`, `Client_Elite`, `Client_Growrk`,
-  `Client_Prudential`. Five are declared **only** on `_Model_Growrk_Unit`; `_Model_Aig_Unit` extends
-  `_Model_Client_Unit` and declares none. `c_lastModified` is declared in **no** model anywhere in
-  `_underscore`.
-- So the field list is **neither** AIG's schema, **nor** AIG's metadata, **nor** any model class AIG
-  uses — it is exactly **four other tenants'** column set.
-
-**Hypothesis (not proven):** `_underscore/Model.php` (~676–687) caches query results as
-`_Database::$_modelCache[$this::DATABASE][$sql]`, and `DATABASE` is the shared **alias** `'Client'`
-— *not* the tenant schema name — so two tenants collide on the same cache key (the same alias-keying
-already documented in the gotcha above). **Unknown: whether that static survives across requests
-under PHP-FPM.** That single unknown is the difference between a harmless within-request artifact and
-a **cross-tenant data-leak vector**, which is why it must be answered rather than assumed.
-
-**Where to look:** `_underscore/Model.php` ~676–687, `api2/Component/Api/V2/V2.php` ~8918–8931,
-`_underscore/Model/Growrk/Unit.php`, `_underscore/Model/Aig/Unit.php`. Context:
-[AIG entitlement intake](../../../clients/aig/features/entitlement-intake.md).
+**The real generalizable fact** — the beta migration fan-out gap is **not limited to `Client/`; it
+also hits `_modules/<module>/`** — is recorded in
+[non-prod metadata drift repair](../../dbchanges2/workflows/nonprod-metadata-drift-repair.md).
 
 ## Change history
 
+- 2026-08-17 (later pass) — **WITHDRAWN, supersedes the entry below.** The alias-keyed
+  `$_modelCache` cross-tenant-leak hypothesis is **not supported** and is no longer a live security
+  concern. The six `c_` columns are **AIG's own**: `_modules/netsuite/2026-07-10a -
+  UnitInventoryFields.sql` adds them to every client whose `_modules.txt` lists `netsuite`, and
+  `Client_Aig/_modules.txt` contains exactly that; prod `Client_Aig.Units` has all 7 custom columns
+  and beta had simply never run the module file. Running it on beta fixed the write. The wrong
+  conclusion came from comparing beta runtime behavior against a **local `_underscore` checkout on
+  branch `TRUE-80282`** while beta deploys `_sandbox-dev` — the moving-branch hazard the api2
+  architecture doc already warns about. (mhammontree)
 - 2026-08-17 — Recorded an **unproven open question** (TRUE-80562): an AIG nested `Units` write
   emitted four *other* tenants' `c_` columns (1054 → EV-12) although AIG's schema, its
   `CustomRecordFields` metadata, and its model class all declare exactly one custom field. Suspected

package/knowledge/2.0/apps/api2/features/api-payload-interceptors.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-14
-owners: ["mhammontree", "dfranks", "bala", "snaredla"]
+updated: 2026-08-17
+owners: ["mhammontree", "dfranks", "bala", "snaredla", "jcardinal"]
 files:
   - api2/Component/Api/V2/V2.php
   - api2/Controller/Index.php
@@ -448,6 +448,13 @@ and the failing environment**. It is a small table, and the drift is usually exa
 
 ## Change history
 
+- 2026-08-17 — Corroborated that the unguarded-dispatch fatal is **systemic, not client-specific**:
+  the prod "undefined method" issue bucket (`Logs.Issue` ref 3G / id 59) grouped **both**
+  `_Model_Compass_Usa_SalesOrderItem::postPost()` **and** `_Model_Elite_SalesOrder::postPut()` — two
+  different tenants, one shared fragility. (This was the original Compass USA failure on 2026-08-12,
+  before it was mitigated on the 2.0 side and the client's NetSuite sync progressed to an unrelated
+  FK failure downstream.) Reinforces the standing fix direction: guard all four `V2.php` call sites
+  with `method_exists()`. Investigation only, no code change. (jcardinal)
 - 2026-08-14 — TRUE-80489, from building the Compass inactive-standalone-item order guard.
   (1) **A PRE interceptor on a PARENT record fires on the nested child POST, with the CHILD as the
   payload.** `POST /sales-orders/{uuid}/sales-order-items` resolves `SalesOrders` as the

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

@@ -94,6 +94,60 @@ fixing. Until then the caller-side workaround is a follow-up identifier-only `PU
 self-heal that detects the null/mismatched echo (shipped on the BDR funnel side — see
 web-funnel-app.md).
 
+## ⚠ CREATE path: a nested singular FK is matched TENANT-WIDE by VALUE and RE-PARENTED
+
+The forward-singular-FK back-reference machinery has a second, worse manifestation — on the
+**CREATE** path, and the damage is a **stolen child row** rather than a null pointer.
+
+A nested `primaryContactEmailAddress` / `primaryContactPhoneNumber` object is matched **across the
+whole tenant by its VALUE** (`emailAddress` / `phoneNumber`) — **not** by `uuid` — and the matched
+child's back-reference `contactId` is then **flipped to the newest writer**, silently detaching it
+from its previous owner.
+
+**Measured on beta `Client_Aig` 2026-08-17 (TRUE-80562).** Two sequential POSTs each created a new
+Contact (**854** at 10:19, **856** at 10:41). Afterwards:
+
+- Contacts **854 AND 856** both have `primaryContactEmailAddressId = 250` and
+  `primaryContactPhoneNumberId = 18`.
+- `ContactEmailAddresses` row **250** has `contactId = 856`.
+- So contact **854 still points at a child row that now belongs to contact 856** — 854's primary
+  email is effectively **detached**.
+
+**Singular and collection paths DIVERGE — only the forward singular FK re-parents.** The collection
+members were **not** stolen: the nested `contactEmailAddresses` entries produced rows **251/252**
+owned by 854 and **separate new rows 255/256** owned by 856. Same payload, same request — different
+behavior per path.
+
+> **Production implication.** Any two contacts sharing an email address or phone number — spouses, a
+> shared household line, a corporate address — **collapse onto one child row whose owner flips to
+> whoever wrote last**. For AIG this compounds with the `c_aigCustomerId` integer overflow (314 of
+> 353 prod contacts clamped to a single identifier value), so **AIG contact identity on prod is not
+> reliably distinct**. See
+> [AIG entitlement intake](../../../clients/aig/features/entitlement-intake.md).
+
+Same back-reference machinery as the
+[UPDATE-path back-reference injection](#update-path-back-reference-injection-defeats-the-uuid-forced-match-primary-pointer-bug)
+above; treat them as one defect with two symptoms when a platform fix is scoped.
+
+## Matching is "link-AND-UPDATE", not "link" — a matched row is mutated from the payload
+
+A nested related object that **matches** an existing record does not merely link to it — the engine
+also **writes the payload's fields onto that existing row**. So partner-supplied data can **mutate
+shared catalog rows**.
+
+**Measured (beta `Client_Aig`, 2026-08-17):** the nested `unit.item` matched `Client_Aig.Items`
+id **1** by `partNumber`, and the payload's `modelNumber` was then written onto it — `Items` id 1
+`modelNumber` went from `NULL` to a test value, `dtUpdated 2026-08-17 10:41:17`.
+
+> **"Link vs. create" is really "link-and-update vs. create". Matching is not read-only.**
+
+**Caveat on this example — do not over-read it.** The test payload put the **sale item** part number
+in `unit.item`, whereas AIG's real payload sends the **device** part number there. Per the AIG data
+model those are two different row kinds in the dual-purpose `Items` table (sale item =
+`itemCategoryId` NULL; unit/device item = `itemCategoryId` set), so **real traffic would not mutate
+this particular row** — but it would do exactly the same thing to the **device item's** row. The
+behavior is general; the specific row in the measurement is an artifact of the test payload.
+
 ## Per-API overrides (`Apis_RecordFields`)
 
 The base identifier flags above (`Core.RecordFields.isIdentifier`) can be **overridden per API**
@@ -206,6 +260,19 @@ anywhere — no `messages[]`, nothing in the client `Logs` or the core/writer `L
 
 ## Change history
 
+- 2026-08-17 (later pass) — Two new measured behaviors from the TRUE-80562 verification run on beta
+  `Client_Aig`. (1) **CREATE-path re-parenting:** a nested forward singular FK
+  (`primaryContactEmailAddress` / `primaryContactPhoneNumber`) is matched **tenant-wide by VALUE**,
+  not by uuid, and the matched child's back-reference `contactId` is **flipped to the newest writer**
+  — Contacts 854 and 856 both point at `ContactEmailAddresses` 250, which now belongs to 856, so
+  854's primary email is detached. **Collection members are NOT stolen** (rows 251/252 stayed with
+  854; 856 got new rows 255/256), so the singular and collection paths diverge. Prod implication: any
+  two contacts sharing an email/phone collapse onto one child row, compounding the AIG
+  `c_aigCustomerId` overflow. Same back-reference machinery as the 2026-07-20 UPDATE-path bug, but on
+  CREATE and with a stolen child instead of a null pointer. (2) **Matching is link-AND-UPDATE:** a
+  matched nested object is **mutated from the payload** — `unit.item` matched `Items` id 1 by
+  `partNumber` and wrote the payload's `modelNumber` onto it, so partner data can mutate shared
+  catalog rows. (mhammontree)
 - 2026-08-17 — TRUE-80562: the TRUE-79978 **manual one-row beta patch did not survive** — the same
   EV-12 recurred on beta 2026-07-21 (`Logs_Aig.Api` ids 93/95/98) after a tenant reseed (log rows
   call `apiId 2` "AIG Integrations"; beta `Client_Aig.Apis` now names it "Agilant"). Identifier

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

@@ -7,4 +7,4 @@
 | [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/ |
 | [Auditing a client DB that drifted from its models (partially applied module migration)](workflows/client-schema-drift-audit.md) | A recurring 2.0 failure mode: **one client's database drifts from what the PHP models declare**, usually because a `_modules/<module>/` migration was applied to | dbchanges2/Client_Growrk/2026-05-28.sql, dbchanges2/Client_Growrk/2026-08-10c - GrowrkServiceRequestCustomFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10d - GrowrkServiceRequestTypeAndDispositionSeeds.sql, dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Growrk/2026-08-10 - GrowrkUnitInventoryFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10b - GrowrkUnitItemDescriptionAcl.sql, dbchanges2/Client_Growrk/_modules.txt |
 | [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/Client_Compass/2026-08-06 - RemoveBrokenSalesOrderItemPostPostInterceptor.sql, dbchanges2/Core/2026-07-16a - TrackingNumberSignatureTypeRecordField.sql, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql, api2/Config/beta.ini, api2/Config/sandbox-dev.ini, dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql, dbchanges2/Client/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql |
+| [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/Client_Compass/2026-08-06 - RemoveBrokenSalesOrderItemPostPostInterceptor.sql, dbchanges2/Core/2026-07-16a - TrackingNumberSignatureTypeRecordField.sql, dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Aig/_modules.txt, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql, api2/Config/beta.ini, api2/Config/sandbox-dev.ini, dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql, dbchanges2/Client/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql |

package/knowledge/2.0/apps/dbchanges2/workflows/nonprod-metadata-drift-repair.md

@@ -12,6 +12,8 @@ files:
   - dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql
   - dbchanges2/Client_Compass/2026-08-06 - RemoveBrokenSalesOrderItemPostPostInterceptor.sql
   - dbchanges2/Core/2026-07-16a - TrackingNumberSignatureTypeRecordField.sql
+  - dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql
+  - dbchanges2/Client_Aig/_modules.txt
   - dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql
   - api2/Config/beta.ini
   - api2/Config/sandbox-dev.ini
@@ -110,6 +112,34 @@ debugging. That migration's own header states the column must exist for all tena
 > A skipped `07-22a` sits **beside a `07-22b` that ran**. Check file-by-file; a date cutoff will
 > mislead you.
 
+### The gap is NOT limited to `Client/` — `_modules/<module>/` is skipped too
+
+Verified 2026-08-17 on beta `Client_Aig`: **`_modules/netsuite/2026-07-10a - UnitInventoryFields.sql`
+had never run** either, so `Client_Aig.Units` was missing six `c_` columns that **production has**.
+`Client_Aig/_modules.txt` contains `netsuite`, so the client *is* opted in — the file was simply not
+applied. Symptom is identical: **MySQL 1054 on a nested write**, surfaced as EV-12 with a
+`modelSaveError`.
+
+> **Audit the module folders as well as `Client/`.** For each tenant, read its `_modules.txt` and
+> diff every `_modules/<module>/` file against the tenant's actual schema. A `Client/`-only audit
+> reports a clean bill of health on a tenant that is still broken.
+
+**This strengthens the "specific dates were skipped" reading.** The missing module file is dated
+**`2026-07-10a`** — the **same date** as the already-recorded missing
+`Client/2026-07-10a` (`ItemFulfillments.returnAddressId`). Two different fan-out folders both missing
+the same date is far better explained by *that date's run failing* than by "beta is behind as of
+date X."
+
+**⚠ Diagnostic trap: do not attribute an unexpected runtime field list to a model class you read
+locally.** During this session the missing-module 1054 was initially mis-diagnosed as a *cross-tenant
+`$_modelCache` leak*, because the model-class comparison was made against a **local `_underscore`
+checkout on branch `TRUE-80282`** while beta deploys **`_sandbox-dev`**. Beta runtime behavior
+compared to a local checkout on a different branch is **not evidence** —
+`_underscore` is cloned at build time from a moving branch
+([environment-variable-drives-underscore-branch](../../api2/features/environment-variable-drives-underscore-branch.md)).
+Check the environment's built branch **before** concluding anything about model classes; the boring
+"a migration never ran" explanation is the one that keeps being true.
+
 **Fix direction: run the existing pending `Client/` files — do NOT author a new migration**, which
 would duplicate a file already on `_main`. A scoped manual `ALTER` on one tenant unblocks your own
 testing but leaves the other 30 broken; say so when you do it.
@@ -205,6 +235,14 @@ blocked by the id-divergence hazard in item 2 above, which is why both go to jca
 
 ## Change history
 
+- 2026-08-17 (later pass) — Extended the fan-out gap: it **also hits `_modules/<module>/`**, not just
+  `Client/`. Beta `Client_Aig` had never run `_modules/netsuite/2026-07-10a - UnitInventoryFields.sql`
+  despite `_modules.txt` listing `netsuite`, so `Units` lacked six `c_` columns prod has → 1054/EV-12
+  on nested unit writes. Note it is the **same date** as the missing `Client/2026-07-10a`, which
+  favors "specific dates were skipped" over "beta is behind as of date X". Added the **diagnostic
+  trap**: that 1054 was first mis-diagnosed as a cross-tenant `$_modelCache` leak because model
+  classes were read from a **local `_underscore` checkout on branch `TRUE-80282`** while beta deploys
+  `_sandbox-dev` — verify the environment's built branch before blaming code. (mhammontree)
 - 2026-08-17 — TRUE-80562: documented that the **`Client/` fan-out is skipped independently of
   `Core/`** on dev-sandbox — 31 of 33 tenant DBs lack `Entitlements.serviceAddressId` (only
   `Client_Rate`/`Client_Elite` have it) while Core carries the RecordField (2763), so **entitlement

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

@@ -214,32 +214,55 @@ one of them to the maximum.
   (`Logs_Aig.Api` and the core/writer `Logs`), keyed by contract number. **Confirm that before
   assuming the loss is permanent.**
 
-## Open question — cross-tenant field list on nested `Units` writes (mechanism UNPROVEN)
+## RESOLVED — the `Units` 1054 was a missing module migration, NOT a cross-tenant leak
 
-An AIG POST carrying `entitlementUnits` produced an `INSERT INTO Units` that included
+**Supersedes the earlier "cross-tenant field list" open question. There is no leak — do not repeat
+that hypothesis.** An AIG POST carrying `entitlementUnits` produced an `INSERT INTO Units` including
 `c_itemDescription`, `c_lastModified`, `c_chargingBrick`, `c_deviceStatus`, `c_chargingCable`,
-`c_grade` → **MySQL 1054**, surfaced as EV-12 with a `modelSaveError`.
-
-**Verified facts:**
-
-- `Client_Aig.Units` has **only** `c_netsuiteInternalInventoryAssignmentId`, and
-  `Client_Aig.CustomRecordFields` declares only that same one field for `Units` (recordId 31) —
-  AIG's schema and metadata **agree**.
-- Those six columns exist only in `Client_Adyen`, `Client_Elite`, `Client_Growrk`,
-  `Client_Prudential`. Five are declared **only** on `_Model_Growrk_Unit`; `_Model_Aig_Unit` extends
-  `_Model_Client_Unit` and declares none. `c_lastModified` is declared in **no** model anywhere in
-  `_underscore`.
-- So the field list is neither AIG's schema, nor AIG's metadata, nor any model class AIG uses — it is
-  **exactly four other tenants' column set**.
-
-**Hypothesis — NOT PROVEN, do not repeat as fact.** `_underscore/Model.php` (~676–687) caches query
-results as `_Database::$_modelCache[$this::DATABASE][$sql]`, where `DATABASE` is the shared **alias**
-(`'Client'`), not the tenant schema name. It is **unknown** whether that static survives across
-requests under PHP-FPM. That distinction is the difference between a harmless within-request artifact
-and a **cross-tenant data-leak vector**, so it needs a focused security review before anyone dismisses
-it. Entry points: `_underscore/Model.php` ~676–687, `api2/Component/Api/V2/V2.php` ~8918–8931,
-`_underscore/Model/Growrk/Unit.php`, `_underscore/Model/Aig/Unit.php`. See
-[per-client database connections](../../../2.0/apps/_underscore/features/per-client-database-connections.md).
+`c_grade` → **MySQL 1054**. Those are **AIG's own fields**:
+
+- `dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql` adds all six columns **and**
+  their `CustomRecordFields` rows to every client whose `_modules.txt` lists `netsuite`.
+  **`Client_Aig/_modules.txt` contains exactly `netsuite`** — AIG is opted in.
+- **Prod `Client_Aig.Units` has all 7 custom columns.** Beta had never run the module file — the same
+  execution gap as `Entitlements.serviceAddressId`. After running it manually on beta `Client_Aig`,
+  `Units` gained all 7 columns and the nested unit write succeeded with those fields present.
+- The wrong conclusion came from comparing beta runtime behavior against a **local `_underscore`
+  checkout on branch `TRUE-80282`** while beta deploys `_sandbox-dev`. See
+  [per-client database connections](../../../2.0/apps/_underscore/features/per-client-database-connections.md)
+  and [non-prod metadata drift repair](../../../2.0/apps/dbchanges2/workflows/nonprod-metadata-drift-repair.md).
+
+## Verified end-to-end with the full real-shaped payload (TRUE-80562, 2026-08-17)
+
+`POST /v2/entitlements` on `api.beta.togahub.com` returned **201 with `entitlementUnits`
+INCLUDED** — 1 unit, 3 coverage types (`C001`/`C002`/`C039`), 1 fulfillment method, 3 contact email
+addresses.
+
+> **This supersedes the earlier partial verification.** Removing `entitlementUnits` was **only a
+> diagnostic isolation step**. **AIG must keep sending it — the unit is the covered device.** Their
+> payload was never wrong.
+
+## `Entitlements.number` carries a UNIQUE key — a replay 400s, it is not idempotent
+
+Re-POSTing an already-created contract number returns **EV-10 / MySQL 1062** *"Duplicate entry … for
+key `Entitlements.number`"* as an **HTTP 400**. This matters against AIG's documented
+[scheduled re-send model](#feed-is-a-scheduled-re-send-batch-not-one-shot--self-healing): the feed is
+safe **only while it re-sends unacknowledged contracts**. A bulk replay or back-fill over
+already-created contracts will 400 per row — plan for that before running one.
+
+## Beta test data left behind by TRUE-80562 (clean-up list)
+
+For whoever cleans up beta `Client_Aig` (row ids only — do not copy the QA contact PII anywhere):
+
+- `Entitlements` id **838** (number `1000045957545`) and the 10:41 entitlement (number
+  `1000045957546`).
+- `Contacts` **854** and **856**, with the cross-linked primary email row **250** / phone row **18**
+  described in
+  [nested-relationship writes](../../../2.0/apps/api2/features/nested-relationship-writes.md).
+- `Items` id **1** — `modelNumber` polluted with a test value; **revert to `NULL`**.
+- **Beta `Client_Aig` had two migrations applied MANUALLY this session** (`Client/2026-07-22a`
+  `serviceAddressId` ALTERs, and the `_modules/netsuite/2026-07-10a` module file), so this tenant is
+  now **ahead of whatever the beta executor believes it has applied**.
 
 ## Business Unit (`UserDefined2`) — answered and DROPPED (nothing to build)
 
@@ -463,6 +486,18 @@ this interceptor or use this dual-purpose Items pattern.
 
 ## Change history
 
+- 2026-08-17 (later pass) — **Correction + final verification, supersedes two points in the entry
+  below.** (1) The nested-`Units` "cross-tenant field list" open question is **WITHDRAWN** — the six
+  `c_` columns are AIG's **own**, added by `_modules/netsuite/2026-07-10a` to every client whose
+  `_modules.txt` lists `netsuite` (AIG's does); prod has all 7 columns, beta had never run the module
+  file. Running it on beta fixed the write. The wrong conclusion came from comparing beta runtime
+  against a **local `_underscore` checkout on branch `TRUE-80282`** vs beta's `_sandbox-dev`. (2)
+  Verified end-to-end with the **full real-shaped payload including `entitlementUnits`** — 201 with
+  1 unit / 3 coverage types / 1 fulfillment method / 3 emails; removing `entitlementUnits` earlier was
+  only an isolation step and **AIG must keep sending it**. Also recorded: `Entitlements.number` has a
+  **UNIQUE key**, so a replay of an already-created contract returns EV-10/1062 as HTTP 400 (matters
+  for any bulk back-fill); and a **beta clean-up list** of the rows/manual migrations this session
+  left behind. (mhammontree)
 - 2026-08-17 — TRUE-80562 (beta EV-12 on entitlement intake). The TRUE-79978 **manual beta patch did
   not survive a tenant reseed** — same EV-12 recurred 2026-07-21 (`Logs_Aig.Api` 93/95/98); the fix
   now ships as `dbchanges2/Client_Aig/2026-08-17a`. Recorded the **scope rule** (only correct NULL

package/package.json

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