toga-ai 1.0.589 → 1.0.591

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

@@ -32,7 +32,7 @@
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php |
 | [NetSuite Sales Order sync — ship-to address, phone, and PO reference sourcing](features/netsuite-salesorder-address-phone-sync.md) | `_Trait_Netsuite_SalesOrder` is the **shared** sales-order importer composed into **22 client models** (every client on the dbchanges2 `netsuite` module). | _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Model.php, dbchanges2/_modules/netsuite/2026-08-10a - AddressPhoneNumberApiRoleAcl.sql |
 | [Legacy page meta (Page::meta) & context-scoped ClientRecordFieldSettings](features/page-meta-context-field-settings.md) | `_Model_Core_Page::meta()` is the **legacy** page-meta resolver behind `GET /pages/meta?slug=<slug>` — still the live path for `toga2-supply` and other pre-Surf | _underscore/Model/Core/Page.php, _underscore/Model/Client/TableView.php |
-| [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/Query.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php, api2/Controller/Index.php |
+| [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/Model.php, _underscore/Query.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php, api2/Controller/Index.php |
 | [Persona Name Translation (PersonaTranslations sidecar)](features/persona-name-translation.md) | Serves Persona **names** in multiple languages by adding a per-language **sidecar** table `PersonaTranslations`, reusing the platform's existing metadata-driven | _underscore/Model/Client/PersonaTranslation.php, dbchanges2/Client/2026-07-22b - PersonaTranslations.sql, dbchanges2/Core/2026-07-22a - PersonaTranslationsRecord.sql, dbchanges2/Client/2026-07-22c - PersonaTranslationsAcl.sql, dbchanges2/Client_CompassCanada/2026-07-22 - PersonaTranslationsFrench.sql, toga2-commerce/src/pages/Account/view/MySettingsView.tsx |
 | [Record Change Audit Log (Logs_<Client>.Record / RecordField) — reading a field's history](features/record-change-audit-log.md) | Every 2.0 client schema has a sibling **logs** schema `Logs_<Tenant>` (e.g. | _underscore/Model/Client/Logs/Record.php, _underscore/Model/Client/Logs/RecordField.php, _underscore/Model/Client/Logs/CustomRecordField.php |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql |

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

@@ -6,10 +6,11 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-30
+updated: 2026-08-17
 owners: ["dfranks", "jcardinal", "mhammontree", "apeterson", "kyalamarthi"]
 files:
   - _underscore/Database.php
+  - _underscore/Model.php
   - _underscore/Query.php
   - _underscore/ApiRequest.php
   - _underscore/Model/Client/Logs/Api.php
@@ -177,8 +178,54 @@ here — they live in `Config/*.ini`.)
   (`db_logs`) — the laptop trap there is documented separately in the worker NetSuite bootstrap
   notes.
 
+## WITHDRAWN — the "alias-keyed `$_modelCache` cross-tenant leak" hypothesis (2026-08-17)
+
+**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:
+
+- `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.
+
+**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.
+
+**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
+  mechanism is the **alias-keyed `_Database::$_modelCache['Client'][$sql]`** collision; whether the
+  static survives across PHP-FPM requests is unknown, and that determines whether this is a
+  within-request artifact or a cross-tenant leak. Flagged for security review; no code changed.
+  (mhammontree)
 - 2026-07-30 — Added four framework-level gotchas surfaced while building the all-client email
   queue monitor: the log-DB name has the same never-string-build rule as the client DB;
   `registerClientDatabases()` is unsafe for an all-client loop (INNER JOINs on client+archive

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

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-03
+updated: 2026-08-17
 owners: ["bala", "mhammontree", "tcox"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -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**
@@ -115,6 +169,38 @@ columns matter:
 > Correct the data with an explicit `overrideIsIdentifier = 1`, or (systemic fix, not yet done)
 > change the code so only an explicit `0` removes an identifier and `NULL` means "no override".
 
+### Fix it with a migration — a manual one-row data patch on non-prod DOES NOT SURVIVE
+
+The TRUE-79978 beta fix was applied by hand as a single `UPDATE` on 2026-07-09. The **identical
+EV-12 recurred on beta on 2026-07-21** (3 requests, `Logs_Aig.Api` ids 93 / 95 / 98) with the same
+signature. Evidence the tenant was **reseeded** underneath the patch: those log rows report
+`apiId 2` as *"AIG Integrations"*, while `Client_Aig.Apis` on beta now names id 2 *"Agilant"* — the
+tenant data was rewritten after 2026-07-21, which is also where an incidental
+`overrideIsIdentifier = 1` on one row came from (not a deliberate re-patch).
+
+> **Rule: any `Apis_RecordFields` identifier correction must ship as a `dbchanges2/Client_<Tenant>/`
+> migration.** A manual patch on beta / dev-sandbox evaporates on the next tenant reseed and the
+> bug returns looking brand new. (TRUE-80562.)
+
+**Scope rule when correcting these rows — only touch fields whose BASE flag is already 1.** Fix a
+`NULL` `overrideIsIdentifier` **only** where `Core.RecordFields.isIdentifier = 1`. A `NULL` override
+on a base-`0` field is a harmless no-op; setting it to `1` **adds** an identifier the platform never
+had and changes nested match-vs-create behavior for that API. On beta `Client_Aig` there were 15
+override rows (all `apiId 2`) but only **5** qualified: `recordFieldId` **1202**
+(*Entitlement fulfillment types.Name*), **1216** (*Entitlement fulfillment methods.Name*), **1259**
+(*Entitlement units.Unitid*), **1386** (*Entitlement coverage types.Name*), **1651**
+(*Contacts.Customerid*).
+
+**Expect a next landmine — fix the whole set, not the one field in the error.** Correcting only
+1202 moved the same EV-12 onto `entitlementFulfillmentMethod` (1216), because
+`_Model_Aig_Entitlement::prePost` injects **both** name-only objects. Audit every qualifying row in
+one migration.
+
+**Diagnostic fingerprint:** the EV-12's `searchableIdentifierFields` list is the record's identifier
+set **minus the stripped field** — e.g. `["id","uuid","code"]` on a record whose identifiers are
+Id/Uuid/Code/**Name** means `name` was stripped by an override row. Read that list first; it names
+the culprit without any DB query.
+
 **Build divergence warning.** The `Apis_RecordFields` override feature (reading
 `overrideIsIdentifier`/`overrideChildPolicy`) was introduced 2026-03-20 (api2 commit `624146d`
 "Cache custom fields and API override lookups"). Environments on **older** builds ignore the
@@ -174,6 +260,29 @@ 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
+  corrections must ship as a `dbchanges2/Client_<Tenant>/` migration. Added the **scope rule** (only
+  fix `NULL` overrides where `Core.RecordFields.isIdentifier = 1` — 5 of 15 AIG rows qualified:
+  1202/1216/1259/1386/1651), the **next-landmine** warning (fixing 1202 alone moves the EV-12 to
+  1216 because `prePost` injects both objects), and the **`searchableIdentifierFields` fingerprint**
+  (base identifier set minus the stripped field names the culprit without a query). Verified
+  2026-08-17: `POST /v2/entitlements` on beta returned 201 with both injected fields resolved.
+  (mhammontree)
 - 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

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 |
+| [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

@@ -6,14 +6,19 @@ project: Database Changes
 client: shared
 type: workflow
 status: active
-updated: 2026-08-14
+updated: 2026-08-17
 owners: ["mhammontree", "bala"]
 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
+  - dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql
+  - dbchanges2/Client/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql
 related:
   - ../architecture.md
   - ./client-schema-drift-audit.md
@@ -41,8 +46,12 @@ exercise TOGa Supply Fulfill & Ship (TRUE-80494).
 ## Steps
 
 1. **Identify which cluster the environment actually reads.** `api.beta.togahub.com` reads the
-   **dev-sandbox** cluster (`api2/Config/beta.ini` `[database] hostname =
-   dev.sandbox.database.togahub.com`) — "beta" is not its own database. Fix the right DB.
+   **dev-sandbox** cluster — "beta" is not its own database. Fix the right DB. Confirmed again
+   2026-08-17 from the other side: **`api2/Config/sandbox-dev.ini`** carries
+   `[api] _ = "https://api.beta.togahub.com/v2"` and `hostname = dev.sandbox.database.togahub.com`.
+   So the toga-db alias to target is **`dev-sandbox`**, *not* `client-beta` — e.g. `Client_Aig`
+   exists only in **prod and dev-sandbox** and is absent from `client-beta` entirely. Picking the
+   wrong alias wastes a full diagnostic cycle.
 2. **Full-table compare the small metadata tables, prod vs. target.** `ApiPayloadInterceptors` in
    particular is small enough to diff wholesale, and the drift is typically **exactly one row**
    (dev-sandbox was missing `(recordId 28, PRE, POST)`, so `prePost` never defaulted
@@ -78,6 +87,76 @@ exercise TOGa Supply Fulfill & Ship (TRUE-80494).
 6. **Re-test the feature end-to-end in that environment**, then record what is still missing so the
    next person doesn't rediscover it.
 
+## The `Client/` fan-out is skipped independently of `Core/` — and the gap is NON-CONTIGUOUS
+
+Measured on dev-sandbox 2026-08-17 (TRUE-80562): **31 of 33 tenant DBs lack
+`Entitlements.serviceAddressId`** (only `Client_Rate` and `Client_Elite` have it), while
+**Core does have the RecordField (id 2763)**. So `Core/2026-07-22a` ran and the
+**`Client/` fan-out of the same change did not.** Symptom: **EV-10 / MySQL 1054 "Unknown column
+'serviceAddressId'" on every entitlement write** — for 31 tenants, not just the one you are
+debugging. That migration's own header states the column must exist for all tenants *before* the
+`_underscore` code deploys, so the code is live against schemas that never got the column.
+
+> **Do not conclude "beta is behind as of date X."** The gap is **partial and non-contiguous** —
+> verified against each file's actual `ALTER`:
+>
+> | State | `Client/` file |
+> |---|---|
+> | **MISSING** | `2026-07-10a` ItemFulfillments.returnAddressId |
+> | **MISSING** | `2026-07-16a` TrackingNumbers.signatureType |
+> | **MISSING** | `2026-07-22a` Entitlements.serviceAddressId |
+> | **MISSING** | `2026-07-28a` TicketStages.ticketTypeId |
+> | PRESENT | `2026-07-17` Items.isFulfillable |
+> | PRESENT | `2026-07-22b` TrackingNumbers.length / weightMeasureId |
+>
+> 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.
+
+**LEAD (unproven) — duplicate letter suffixes may be why the executor skipped it.** `dbchanges2/Client/`
+contains **three** files all named `2026-07-22a` (`EntitlementServiceAddressId`, `MeasureUomColumns`,
+`Notification&PersonaTranslations`), violating the one-letter-per-day naming contract in
+[architecture.md](../architecture.md). The skipped file is one of that trio. **Worth checking whether
+the executor dedupes on date+letter** — if it does, the naming violation is the root cause and the
+same trap is live wherever letters collide.
+
+**Rule violation worth fixing separately:** `Client/2026-07-23a -
+EntitlementServiceAddressIdFieldPermission.sql` references **`Core.RecordFields` and `Core.Records`
+from a `Client/` fan-out file**, breaking the hard one-database-per-file cluster-isolation rule. Its
+own comment says *"same server"* — which is exactly the trap the rule exists for: it works on
+dev-sandbox (shared cluster) and would fail in production, where `Core` is a separate cluster.
+
 ## Environment facts worth knowing before you test here
 
 - **NO carrier can be tested on ANY non-production environment.** Beta runs
@@ -156,6 +235,25 @@ 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
+  writes EV-10/1054 for 31 tenants**. The gap is **partial and non-contiguous** (missing 07-10a,
+  07-16a, 07-22a, 07-28a; present 07-17, 07-22b), so a date cutoff misleads. Fix = run the existing
+  pending files, never author a duplicate. Recorded the unproven **duplicate-letter lead** (three
+  `Client/2026-07-22a` files; the skipped one sits beside a `07-22b` that ran — check whether the
+  executor dedupes on date+letter) and a **cluster-isolation violation** in `Client/2026-07-23a`
+  (reads `Core.RecordFields`/`Core.Records` from a `Client/` file, justified as "same server").
+  Step 1 now cites `api2/Config/sandbox-dev.ini` and the `dev-sandbox` vs `client-beta` alias trap.
+  (mhammontree)
 - 2026-08-14 — Recorded that metadata drift runs in **both** directions: a cleanup migration that
   *removed* a row in production is as easily skipped in non-prod as an additive one. Evidence —
   `Client_Compass/2026-08-06 - RemoveBrokenSalesOrderItemPostPostInterceptor.sql` had never run on

package/knowledge/clients/aig/INDEX.md

@@ -3,5 +3,5 @@
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
 | [AIG Contract Reconciliation & Dealer Programs (STS_001 / SA_001)](features/contract-reconciliation.md) | 2.0 | How to reconcile an **AIG contract sales sheet** against the `Client_Aig` tenant, and the durable finding that the **Staples Advantage.com (`SA_001`) program do | _underscore/Model/Client/Entitlement.php, _underscore/Model/Aig/Entitlement.php, _underscore/Model/Client/Contact.php, _underscore/Model/Aig/Contact.php |
-| [AIG Entitlement Intake & SaleItem Code Resolution](features/entitlement-intake.md) | 2.0 | The `_Model_Aig_Entitlement::prePost` interceptor below is the code path for AIG protection-plan entitlements arriving as `api2` V2 JSON POSTs — and that path * | _underscore/Model/Aig/Entitlement.php, api2/Component/Api/V2/V2.php, dbchanges2/Client_Aig/2026-06-18a - TRUE-79534 AIG SaleItem codes.sql |
+| [AIG Entitlement Intake & SaleItem Code Resolution](features/entitlement-intake.md) | 2.0 | The `_Model_Aig_Entitlement::prePost` interceptor below is the code path for AIG protection-plan entitlements arriving as `api2` V2 JSON POSTs — and that path * | _underscore/Model/Aig/Entitlement.php, _underscore/Model/Aig/Unit.php, api2/Component/Api/V2/V2.php, api2/Config/sandbox-dev.ini, dbchanges2/Client_Aig/2026-06-18a - TRUE-79534 AIG SaleItem codes.sql, dbchanges2/Client_Aig/2026-08-17a - TRUE-80562 AIG API identifier overrides.sql |
 | [AIG (Staples Protection Plan)](profile.md) | 2.0 | AIG is the warranty underwriter behind the **Staples Protection Plan** retail program. |  |

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

@@ -5,12 +5,15 @@ project: API
 client: aig
 type: client-feature
 status: active
-updated: 2026-08-10
+updated: 2026-08-17
 owners: ["mhammontree"]
 files:
   - _underscore/Model/Aig/Entitlement.php
+  - _underscore/Model/Aig/Unit.php
   - api2/Component/Api/V2/V2.php
+  - api2/Config/sandbox-dev.ini
   - dbchanges2/Client_Aig/2026-06-18a - TRUE-79534 AIG SaleItem codes.sql
+  - dbchanges2/Client_Aig/2026-08-17a - TRUE-80562 AIG API identifier overrides.sql
 related:
   - clients/aig/features/contract-reconciliation.md
   - 1.0/apps/library/features/toga2-api-client-and-bridge.md
@@ -18,7 +21,9 @@ related:
   - 2.0/apps/api2/features/nested-relationship-writes.md
   - 2.0/apps/api2/architecture.md
   - 2.0/apps/dbchanges2/architecture.md
+  - 2.0/apps/dbchanges2/workflows/nonprod-metadata-drift-repair.md
   - 2.0/apps/_underscore/architecture.md
+  - 2.0/apps/_underscore/features/per-client-database-connections.md
 ---
 
 ## Summary
@@ -149,6 +154,116 @@ recovered on 07-29 exactly as the resolution above describes. But the creating p
 rows (through 2026-08-04) was **not positively identified** — confirm it in `Logs_Aig.Api` before
 asserting either "intake is entirely down" or "intake is healthy."
 
+> **Partly answered 2026-08-17 (TRUE-80562):** `Logs_Aig.Api` **does** carry non-2xx entitlement
+> writes on beta (ids 93 / 95 / 98, all 400/EV-12 on 2026-07-21), so the "failures only ever land in
+> core `Logs`" reading is too strong — `Logs_Aig` is a usable first stop for beta 4xx. Only 5xx-class
+> failures reliably escape to the core/writer `Logs`.
+
+## Which environment is "beta"? (`api.beta.togahub.com` = **dev-sandbox**)
+
+`api2/Config/sandbox-dev.ini` carries `[api] _ = "https://api.beta.togahub.com/v2"` and a database
+`hostname` of `dev.sandbox.database.togahub.com`. So for AIG/API work, **"beta" resolves to the
+dev-sandbox cluster** (toga-db alias `dev-sandbox`), **not** the `client-beta` alias — which has no
+`Client_Aig` schema at all. **`Client_Aig` exists only in prod and dev-sandbox.** Targeting the wrong
+alias costs a whole diagnostic cycle. See
+[non-prod metadata drift repair](../../../2.0/apps/dbchanges2/workflows/nonprod-metadata-drift-repair.md).
+
+## EV-12 on the injected fulfillment fields — fix it with a MIGRATION (TRUE-80562)
+
+The TRUE-79978 EV-12 (an `Apis_RecordFields` override row with `overrideIsIdentifier = NULL`
+stripping `name` as an identifier) **came back on beta**. The 2026-07-09 manual one-row `UPDATE`
+**did not survive**: the identical error hit `entitlementFulfillmentType` again on **2026-07-21**
+(`Logs_Aig.Api` ids 93 / 95 / 98). The tenant had been **reseeded** — those log rows call `apiId 2`
+*"AIG Integrations"* while beta `Client_Aig.Apis` now names id 2 *"Agilant"*.
+
+> **Manual data patches on beta evaporate. The fix must be a `dbchanges2/Client_Aig/` migration** —
+> shipped as `2026-08-17a - TRUE-80562 AIG API identifier overrides.sql`.
+
+- **Scope rule:** correct a `NULL` `overrideIsIdentifier` **only** where the BASE
+  `Core.RecordFields.isIdentifier = 1`. On a base-`0` field the NULL is a harmless no-op and setting
+  it to `1` would **add** an identifier and change nested match-vs-create behavior. Beta
+  `Client_Aig` had **15** override rows (all `apiId 2`); only **5** qualified — `recordFieldId`
+  **1202** (Entitlement fulfillment types.Name), **1216** (Entitlement fulfillment methods.Name),
+  **1259** (Entitlement units.Unitid), **1386** (Entitlement coverage types.Name), **1651**
+  (Contacts.Customerid).
+- **Fix the whole set — there is a next landmine.** Fixing only 1202 moved the same EV-12 onto
+  `entitlementFulfillmentMethod` (1216), because `prePost` injects **both** name-only objects.
+- **Fingerprint:** the error's `searchableIdentifierFields` is the record's identifier set *minus*
+  the stripped field — `["id","uuid","code"]` on record 186 (identifiers Id/Uuid/Code/**Name**)
+  points straight at `name`.
+- **Verified 2026-08-17:** `POST /v2/entitlements` on `api.beta.togahub.com` returned **201** with
+  both injected fields resolved, 3 coverage types and 3 contact email addresses written.
+
+## ⚠ `Client_Aig.Contacts.c_aigCustomerId` integer overflow — destroying identifiers IN PRODUCTION
+
+**Needs its own ticket; higher priority than TRUE-80562.**
+
+`Client_Aig.Contacts.c_aigCustomerId` is `int unsigned` (max **4,294,967,295**) on **both beta and
+prod**, but AIG customer ids are **13 digits** (e.g. `1000045957545`). MySQL **silently clamps** every
+one of them to the maximum.
+
+- **Measured on prod 2026-08-17:** 353 contacts — **314 (89%) clamped to 4294967295**, 14 NULL, only
+  **26 distinct values** left.
+- **Why it is severe, not cosmetic:** `c_aigCustomerId` is `isIdentifier = 1` in
+  `Client_Aig.CustomRecordFields`, i.e. a **searchable identifier used for nested-object matching**.
+  314 contacts now share one identifier value, so a match on it is ambiguous and can attach an
+  entitlement / email / claim to the **wrong customer**.
+- **Fix direction:** a `dbchanges2/Client_Aig/` migration to `BIGINT UNSIGNED` **stops the bleeding
+  but recovers nothing** — the original values are destroyed in the column. **Possible recovery
+  source:** the true ids are in the logged `requestPayload` of inbound entitlement POSTs
+  (`Logs_Aig.Api` and the core/writer `Logs`), keyed by contract number. **Confirm that before
+  assuming the loss is permanent.**
+
+## RESOLVED — the `Units` 1054 was a missing module migration, NOT a cross-tenant leak
+
+**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**. 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)
 
 AIG (Alissa, 2026-05-04) confirmed the **Business Unit / Value** field needs **nothing returned to
@@ -320,6 +435,20 @@ this interceptor or use this dual-purpose Items pattern.
   find a searchable identifier for the injected object. Root cause (TRUE-79978) was an
   `Apis_RecordFields` override row that stripped `name` as an identifier — see
   [api2 nested-relationship writes → Per-API overrides](../../../2.0/apps/api2/features/nested-relationship-writes.md).
+- **The empty-`partNumber` variant is CONFIRMED LIVE (observed 2026-08-17, not inferred).** A
+  payload with `saleItem.partNumber = ""` resolved to `saleItemId = 10` — on beta a row with
+  `partNumber = ''` and description *"2YR Tablet: ($300-$399.99)"*, an item **unrelated to the
+  submitted contract**. The same payload with a real code (`SP-3DAD-LTP2`) correctly resolved to
+  id 1. The doc predicted this; it now has a live sighting. The guard clause is still not written.
+- **`prePost` OVERRIDES the client-submitted fulfillment method and nothing signals it.** A payload
+  sending `entitlementFulfillmentMethod {name: "Credit"}` produced a stored record of **"Gift Card"**
+  plus an injected type **"Reimbursement"** — the interceptor populates both from
+  `Items_EntitlementFulfillmentMethods`/`Types` for the matched sale item and **discards the
+  client-supplied value**. This may be intended (catalog is the authority), but the **201 response
+  does not signal the override**, so a partner cannot tell their value was dropped. **Open question
+  for the integration owner** — confirm intent, and consider echoing the resolved values.
+- **Beta 4xx entitlement writes DO appear in `Logs_Aig.Api`** (ids 93/95/98, 2026-07-21). Check the
+  client log first for validation failures; reserve the core/writer `Logs` hunt for 5xx.
 - **A lookup miss yields an empty `$itemId` that crashes the next query (confirmed in prod,
   TRUE-79534).** The unguarded line is **`_underscore/Model/Aig/Entitlement.php:48`** in `prePost`,
   reached from **`api2/Component/Api/V2/V2.php:2601`**. The malformed statement it emits is:
@@ -357,6 +486,33 @@ 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
+  `overrideIsIdentifier` where base `Core.RecordFields.isIdentifier = 1` — 5 of 15 rows:
+  1202/1216/1259/1386/1651), the **next landmine** (fixing 1202 alone moves the error to 1216 since
+  `prePost` injects both objects), and the `searchableIdentifierFields` fingerprint. **Verified: 201
+  on `api.beta.togahub.com`.** Added: `api.beta.togahub.com` = **dev-sandbox** per
+  `api2/Config/sandbox-dev.ini` (`Client_Aig` exists only in prod + dev-sandbox, never
+  `client-beta`); beta **4xx** writes DO land in `Logs_Aig.Api`. New **⚠ prod data defect**:
+  `Contacts.c_aigCustomerId` is `int unsigned` while AIG ids are 13 digits — **314 of 353 prod
+  contacts clamped to 4294967295** on an `isIdentifier` field (ambiguous nested matching); needs its
+  own ticket, BIGINT migration does not recover the values. New **open question**: a nested `Units`
+  write emitted four other tenants' `c_` columns (1054) — alias-keyed `_modelCache` hypothesis,
+  unproven, needs security review. Confirmed the empty-`partNumber` trap live (`saleItemId = 10`)
+  and that `prePost` silently overrides a submitted `entitlementFulfillmentMethod`. (mhammontree)
 - 2026-08-10 — Read-only prod investigation (no code/SQL changed). Added **Verified prod state**:
   the TRUE-79534 catalog **is** loaded (`Client_Aig.Items` = 2,212 rows — 1,110 `ASI-*` / 558
   `SM-*` / 37 `SP-*`; `ASI-2YG2` present), so a future 1064 here is the **empty-input** variant,

package/package.json

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