toga-ai 1.0.590 → 1.0.591

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/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.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",