toga-ai 1.0.282 → 1.0.284

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

@@ -4,6 +4,7 @@
 |-----|---------|-------|
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
 | [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql |
+| [Address Validation (carrier waterfall + validateAddress scripted endpoint)](features/address-validation.md) | `_Model_Client_Address::validateAddress` verifies a US address against a **carrier waterfall (USPS → FedEx → UPS)** and returns a single canonical, carrier-norm | _underscore/Model/Client/Address.php |
 | [Assortment Name Translation (AssortmentTranslations sidecar)](features/assortment-name-translation.md) | Serves Assortment (product-grouping) **names** in multiple languages by adding a per-language **sidecar** table `AssortmentTranslations`, reusing the platform's | _underscore/Model/Client/AssortmentTranslation.php, dbchanges2/Client/2026-06-26a - AssortmentTranslations.sql, dbchanges2/Core/2026-06-26a - AssortmentTranslationsRecord.sql, dbchanges2/Client/2026-06-26b - AssortmentTranslationsAcl.sql |
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |

package/knowledge/2.0/apps/_underscore/features/address-validation.md

@@ -0,0 +1,76 @@
+---
+title: "Address Validation (carrier waterfall + validateAddress scripted endpoint)"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-07-07
+owners: [mhammontree]
+files:
+  - _underscore/Model/Client/Address.php
+related:
+  - ../../api2/features/scripted-api-post-body-args.md
+  - ../../api2/architecture.md
+  - ../../../clients/rate/features/whole-home-warranty-purchase-guard.md
+---
+
+## Summary
+
+`_Model_Client_Address::validateAddress` verifies a US address against a **carrier
+waterfall (USPS → FedEx → UPS)** and returns a single canonical, carrier-normalized
+address. It is exposed to the frontend as the **global** scripted endpoint
+`GET /addresses/validateAddress`, and is also callable server-side by any model/interceptor
+that needs to validate + normalize an address before persisting it (e.g. the Rate
+Whole Home Warranty purchase guard).
+
+## Key files / entry points
+
+- `_Model_Client_Address::validateAddress(&$api, $address1, $address2, $city, $state, $zip)`
+  (`_underscore/Model/Client/Address.php`) — runs USPS, then FedEx, then UPS.
+  - **On success** (carriers agree) returns keys: `success:true`, `address1`, `address2`,
+    `city`, `state` (2-letter code), `zipCode`, `country`. UPS additionally supplies
+    `zip4`/`zip5`.
+  - **On failure** (all carriers fail) returns the **last (UPS) response** with
+    `success:false` (and an `error`).
+
+## The scripted endpoint is registered in the DB, not in source (parity gap)
+
+The `GET /addresses/validateAddress` endpoint the frontend calls is wired as a **global**
+scripted endpoint in **`Core.RecordScripts`** (id 17: `recordId` 13 = Addresses, method
+`GET`, route `validateAddress`, `phpMethod` `validateAddress`). Verified in production
+2026-07-07.
+
+- It is **not** in any client-level `CustomRecordScripts` (Rate's is empty), and it is
+  **not** present in `dbchanges2` source — the registration exists **only in the live DB**.
+  Treat this as a known source/DB parity gap: you will not find the endpoint by grepping
+  `dbchanges2`.
+- **Dispatch precedence:** the V2 engine checks `Core.RecordScripts` **before** a client's
+  `CustomRecordScripts`, so a global script wins for every client unless a client overrides it.
+- **Response path:** a scripted method's return value is placed at
+  `data.<record>.<route>` in the API envelope — so `validateAddress` (record = Addresses,
+  route = validateAddress) returns to **`data.addresses.validateAddress`**, which is exactly
+  what the frontend reads.
+
+## Client variations
+
+None — this is shared engine + framework behavior. The carrier credentials are resolved
+per the standard client carrier config.
+
+## Gotchas / known issues
+
+- **DB-only registration.** Because the `Core.RecordScripts` row is not in `dbchanges2`,
+  the endpoint's existence is invisible to source search and is not reproduced by replaying
+  migrations into a fresh DB. Register scripted endpoints in `dbchanges2` going forward.
+- **Waterfall requires agreement on success.** The success shape is only returned when the
+  carriers agree; a `success:false` result carries the last (UPS) response, not a merged one.
+
+## Change history
+
+- 2026-07-07 — Documented `_Model_Client_Address::validateAddress` (USPS→FedEx→UPS waterfall
+  + normalized success shape) and the global `GET /addresses/validateAddress`
+  (`Core.RecordScripts` id 17) endpoint, including the dispatch precedence, the
+  `data.<record>.<route>` response path, and the dbchanges2 source/DB parity gap
+  (registration lives only in the live DB). Prod-verified while building the Rate WH purchase
+  guard (TRUE-79533). (mhammontree)

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

@@ -6,6 +6,7 @@
 | [Multi-Client (Cross-Client) Data Retrieval](features/cross-client-data-retrieval.md) | A single authenticated V2 GET listing can return records across **many** clients (designed for 1000+) that the caller is entitled to, honoring **each target cli | api2/Component/Api/CrossClient/CrossClient.php, api2/Component/Api/V2/V2.php, api2/Controller/Index.php, api2/_.php, _underscore/Model/Cache/Table.php, _underscore/Model/Cache/Tables/Client.php, dbchanges2/Core/2026-06-30b - CacheClusterRegistrationAndRecordTtl.sql, dbchanges2/Cache/2026-06-30a - MultiClientCacheTables.sql |
 | [Encrypted-User-UUID Auth Handoff (/auth/encrypted-user-uuid)](features/encrypted-user-uuid-auth-handoff.md) | `POST /auth/encrypted-user-uuid` is the intended **cross-client / SSO-handoff identity mechanism**: given an encrypted `{client, user}` UUID pair, it mints a fr | api2/Component/Api/CrossClient/CrossClient.php |
 | [Language Translation Layer (audience.language + sidecar tables)](features/language-translation-layer.md) | Serves the same TOGa data (Item title/description/longDescription, expanding later) in multiple languages without forking the schema or breaking English consume | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, _underscore/Model/Core/Setting.php, _underscore/Model/Core/RecordField.php, _underscore/Model/Core/DefaultGlobalSetting.php, _underscore/Model/Client/ItemTranslation.php, dbchanges2/Client/2026-06-23a - ItemTranslations.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Core/2026-06-23a - RecordFieldsTranslationColumn.sql, dbchanges2/Core/2026-06-23b - ItemTranslationsRecord.sql |
+| [Nested-relationship writes & child matching (link vs. create)](features/nested-relationship-writes.md) | When a 2.0 API write payload (`POST`/`PUT`) contains a **nested related object** (e.g. | api2/Component/Api/V2/V2.php |
 | [POST + JSON-body args for scripted APIs](features/scripted-api-post-body-args.md) | The V2 engine can run a Record Script (scripted API) for a **POST** request, and a scripted API can receive its arguments from the **JSON request body** instead | api2/Component/Api/V2/V2.php |
 | [Surface action-state via the surface=<slug> request option (M2M-safe)](features/surface-meta-option.md) | An opt-in V2 engine request option, `surface=<slug>`, that attaches per-record UI action state (`isVisible`/`isEnabled`) to a GET response **under `meta.surface | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Surface.php |
 | [Tickets API (/v2/tickets)](features/tickets-api.md) | The generic ticket endpoint of the 2.0 REST API. | Component/Api/V2/V2.php |

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

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: architecture
 status: active
-updated: 2026-06-08
-owners: [jcardinal]
+updated: 2026-07-07
+owners: [jcardinal, bala]
 files:
   - api2/Controller/Index.php
   - api2/Component/Api/V2/V2.php
@@ -34,6 +34,9 @@ framework is **pulled at deploy, not vendored**. Composer deps: `sentry/sentry`,
 **Critical rules:** every action method must return the exact envelope
 `['success' => bool, 'data' => mixed, 'errors' => array]` — never a raw string or bare array.
 On error: `success=false`, `data=null`, `errors=[...]`. Deviating breaks API consumers silently.
+A **nested related object** in a write payload links to an existing record **only** by an
+identifier (`uuid`); a non-unique custom field (e.g. `c_employeeXid`) is not a match key and
+forces a **new-record insert** every write — link with `contact: {uuid}`.
 
 ## Dependencies
 

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

@@ -0,0 +1,80 @@
+---
+title: "Nested-relationship writes & child matching (link vs. create)"
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-07-07
+owners: ["bala"]
+files:
+  - api2/Component/Api/V2/V2.php
+related:
+  - ../architecture.md
+---
+
+## Summary
+
+When a 2.0 API write payload (`POST`/`PUT`) contains a **nested related object** (e.g. a unit
+payload with an embedded `contact: {…}`), the api2 V2 engine decides per nested object whether to
+**link an existing** related record or **create a new one**. The rule that governs this is narrow
+and easy to get wrong:
+
+> A nested related object is matched to an existing record **only** by fields flagged as
+> **identifiers** (`uuid` is the identifier field). If the object contains an identifier, the
+> engine **loads and links** the existing record. If it contains no identifier field, the engine
+> **creates a new child record** — even if the object carries a value (like a custom field) that
+> *looks* unique to a human.
+
+Implemented in `Component/Api/V2/V2.php` (`getForeignKeyValue()` / the nested-write matching in
+`processRoutePairs()`).
+
+## How it works
+
+- **`uuid` is the identifier field.** A nested object of `{uuid: <existing-uuid>}` forces a
+  **MATCH**: the engine loads that existing record and links the parent to it — it never creates.
+  (The numeric internal `id` also links an existing record.)
+- **A non-unique custom field is NOT a match key.** Passing a nested object that contains only a
+  plain custom field — e.g. `contact: {c_employeeXid: 'X208000'}` — provides **no identifier**, so
+  the engine has nothing to match on and **inserts a new child record every time**. It does not
+  matter that `c_employeeXid` is conceptually the employee's unique key; it is not flagged as an
+  identifier, so the engine ignores it for matching.
+
+## Correct pattern
+
+To **link** an existing related record, send its identifier:
+
+```
+"contact": { "uuid": "<existing-contact-uuid>" }   // links; never creates
+```
+
+To **create** a new related record, send its data **without** an identifier (and accept that a new
+row is written). Never rely on a non-identifier field (a custom field, a name, an email) to
+de-duplicate — the engine will not use it to match, and you will accumulate duplicate empty child
+rows on every write.
+
+If you need to link by a business key (like an employee XID), **resolve that key to a uuid in your
+caller first** (e.g. build a `key → uuid` map), then send `{uuid}`.
+
+## Gotcha
+
+- **Nested write with only a non-identifier field silently creates duplicates.** This is a
+  duplicate-generating footgun: each write inserts a new empty child and the parent links to a
+  fresh shell (or is left with a NULL FK). It compounds on any cron/integration that writes the
+  same entity repeatedly. Root-caused in production on the Prudential device-sync cron, which sent
+  `contact: {c_employeeXid}` and generated ~893k empty Contact rows (~5,600/day). See
+  [Prudential device import + contact linking](../../../clients/prudential/features/device-information-import-and-contact-linking.md).
+
+## Change history
+
+- 2026-07-07 — Documented that api2 nested-relationship writes match an existing child **only** by
+  identifier (`uuid`); a non-unique custom field is not a match key and forces a new-record insert.
+  Correct pattern is `contact: {uuid}` (resolve business keys to uuid in the caller). Surfaced by
+  the Prudential "null null" contact-export incident. (bala)
+
+## Related docs
+
+- [api2 architecture](../architecture.md) — the V2 CRUD engine (`processRoutePairs`).
+- [Prudential device import + contact linking](../../../clients/prudential/features/device-information-import-and-contact-linking.md)
+  — the production incident that exposed this behavior.

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

@@ -6,8 +6,8 @@ project: Database Changes
 client: shared
 type: architecture
 status: active
-updated: 2026-07-02
-owners: [jcardinal, mhammontree]
+updated: 2026-07-07
+owners: [jcardinal, mhammontree, bala]
 files:
   - Core/
   - Client/
@@ -233,6 +233,17 @@ query into a temporary derived table, so the outer `DELETE` no longer "sees" a l
 its own target. Used in `2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql` to prune
 duplicate `ItemFulfillments` rows.
 
+### FK back-reference cycle — re-point detail rows, don't delete them
+
+When deduping a parent (e.g. `Contacts`) that has a back-reference FK to its own detail rows
+(`primaryContactEmailAddressId` → `ContactEmailAddresses`, `primaryContactPhoneNumberId` →
+`ContactPhoneNumbers`), deleting the non-keeper detail rows breaks the cycle. Instead re-point
+`ContactEmailAddresses`/`ContactPhoneNumbers.contactId` to the keeper (safe because `contactId`
+is non-unique on those tables → no collision), which preserves every primary pointer. Detail
+tables with a `UNIQUE(parentId, childId)` (e.g. `ContactAddresses`) can't be re-pointed —
+null-then-delete those. Then delete the non-keeper parents via the materialized double-nested
+subquery. Used in `Client_Prudential/2026-07-07 - Contact Dedup Merge.sql`.
+
 ## Relationship to the rest of 2.0
 
 `dbchanges2` is registered as a **2.0 core repo** (`role: core` in `registry.json`) — it is

package/knowledge/INDEX.md

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 11 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 13 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 14 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
 - **togadesk** (TOGa Desk) — 8 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 6 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
@@ -17,9 +17,9 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 22 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 24 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 27 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 9 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 10 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)

package/knowledge/clients/prudential/INDEX.md

@@ -4,6 +4,7 @@
 |-----|-----------|---------|-------|
 | [Prudential: Dell ASN units PRE/POST interceptor (legacy key + flat tracking)](features/dell-asn-units-interceptor.md) | 2.0 | After the tracking-number bridge migration, the ASN unit route was renamed (`advance-shipping-notice-units` → `advance-shipping-notice-item-units`), so the inhe | _underscore/Model/Prudential/AdvanceShippingNotice.php, dbchanges2/Client_Prudential/2026-06-10 - AsnUnitsInterceptor.sql |
 | [Prudential: Dell LCH IOP transmissions (LCHRequestV2)](features/dell-lch-iop-transmissions.md) | 1.0 | Outbound order transmissions from the 1.0 worker tier to Dell's Lifecycle Hub (LCH) ITSM integration. | library/app/api/delllch.php, worker/crons/toga2/prudential/transmissions_to_dell.php, worker/crons/toga2/prudential_beta/transmissions_to_dell_india.php, worker/crons/toga2/prudential_beta/transmissions_to_dell_ireland.php, worker/crons/toga2/prudential_beta/transmissions_to_dell_usa.php |
+| [Prudential: Device information import + unit→contact linking (import_device_information.php)](features/device-information-import-and-contact-linking.md) | 1.0 | Prudential's **device-sync** cron (`worker/crons/toga2/prudential/import_device_information.php`) pulls device/asset records (from ServiceNow / the Dell CMDB fe | worker/crons/toga2/prudential/import_device_information.php, worker/crons/toga2/prudential/backfill_unit_contacts.php, dbchanges2/Client_Prudential/2026-07-07 - Contact Dedup Merge.sql |
 | [Prudential: Service Request Regional Address Validation](features/service-request-address-validation.md) | 2.0 | The `prePost` interceptor on `_Model_Prudential_ServiceRequest` validates `deliverToAddress` fields differently depending on which Prudential regional customer | _underscore/Model/Prudential/ServiceRequest.php |
 | [Prudential Order Shipped Email — transmit_ordershipped_updates_prudential.php](features/transmit-ordershipped-email.md) | 1.0 | Cron script that transmits "Order Shipped" updates to ServiceNow (RITM) and sends a shipped notification email to the end user. | worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php, worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php, worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php, worker/crons/toga2/prudential_beta/generate_sales_and_purchase_orders_from_service_requests.php |
 | [Prudential Financial](profile.md) | 2.0 | Prudential is a TOGA client whose device-fulfillment flow is driven by **Dell** via the Dell API (`Client_Prudential.Apis.id = 2`). |  |

package/knowledge/clients/prudential/features/device-information-import-and-contact-linking.md

@@ -0,0 +1,151 @@
+---
+title: "Prudential: Device information import + unit→contact linking (import_device_information.php)"
+framework: "1.0"
+repo: worker
+project: Worker
+client: prudential
+type: client-feature
+status: active
+updated: 2026-07-07
+owners: ["bala"]
+files:
+  - worker/crons/toga2/prudential/import_device_information.php
+  - worker/crons/toga2/prudential/backfill_unit_contacts.php
+  - dbchanges2/Client_Prudential/2026-07-07 - Contact Dedup Merge.sql
+related:
+  - ../profile.md
+  - ../../../2.0/apps/api2/features/nested-relationship-writes.md
+---
+
+## Summary
+
+Prudential's **device-sync** cron (`worker/crons/toga2/prudential/import_device_information.php`)
+pulls device/asset records (from ServiceNow / the Dell CMDB feed) and PUTs them into the 2.0
+platform (`Client_Prudential` via the TOGa2 API), writing `Units` and their owning `Contact`.
+Each unit's contact is keyed to an employee by the custom field **`c_employeeXid`**.
+
+This doc records how the cron links a unit to its real employee contact, the production incident
+that came from getting that wrong, and the two remediation pieces (a dedup migration and a
+null-contact backfill cron).
+
+## How it works
+
+- The cron loads **all** existing Prudential contacts once into an in-memory
+  **`c_employeeXid` → keeper uuid** map (`loadPrudentialContactMap`).
+- `resolvePrudentialContactUuid(<XID>)` returns the keeper contact uuid for an employee XID —
+  the **oldest named contact** for that XID. On a genuine miss it creates **exactly one**
+  contact and caches it so the same run never creates a second.
+- All four unit-write payloads link the existing contact by sending **`contact: {uuid: <keeper-uuid>}`**
+  — an identifier the api2 write engine can match — **never** `contact: {c_employeeXid: …}`.
+
+The keeper uuid comes from the resolved map, so every unit for a given employee links to the one
+real contact and no duplicate empty contacts are created.
+
+## Why `contact: {uuid}` and not `contact: {c_employeeXid}`
+
+This is the crux. In the api2 V2 write engine a nested related object is matched to an existing
+record **only** by fields flagged as identifiers (`uuid`). A plain, non-unique custom field like
+`c_employeeXid` is **not** a match key, so a nested `contact: {c_employeeXid: …}` object never
+matches an existing contact — the engine **inserts a new (empty) Contact every time** and links
+the unit to that shell. See the general behavior doc:
+[2.0 api2 — Nested-relationship writes & child matching](../../../2.0/apps/api2/features/nested-relationship-writes.md).
+
+## The production incident (root cause)
+
+The Prudential TOGa Supply contact export showed **"null null"** contact names and blank
+phone/email/XID on ~11.6k of ~27.8k rows, and searching the export by employee name or XID
+returned almost nothing.
+
+**Root cause:** the device-sync cron sent the unit's contact as a nested object containing
+**only `c_employeeXid`**. Because that field is not an identifier, api2 could not match an
+existing Contact, so it **INSERTed a new empty Contact on every run** and either linked the unit
+to that empty shell or left `Units.contactId` NULL. Verified in prod logs: two `PUT /units` for
+the same XID seconds apart each created a **different** new contact (`dtCreated = now`,
+`firstName = null`).
+
+**Blast radius in prod:** ~**893k** Contact rows for only ~**19.5k** real employees (XID
+`X208000` alone had **178k** rows), and ~**23k** Units with `contactId` NULL. The cron was
+generating roughly **5,600 duplicate empty contacts/day**.
+
+## Remediation
+
+Two independent pieces, run **in order**:
+
+1. **Cron fix (deployed to prod, live)** — the in-memory map + `contact: {uuid}` payloads above.
+   This **stops new junk**. It must be deployed before anything cleans up existing junk, or the
+   cleanup regenerates (observed on sandbox).
+2. **Dedup migration** — `dbchanges2/Client_Prudential/2026-07-07 - Contact Dedup Merge.sql`
+   (tested on a full prod copy; **not yet run on prod**). Removes **existing** junk: collapses
+   Contacts to one keeper per `c_employeeXid`. See *Dedup migration* below.
+3. **Null-contact backfill cron** — `worker/crons/toga2/prudential/backfill_unit_contacts.php`
+   (logic tested; **not yet run**). Links `Units` that still have `contactId` NULL, resolving the
+   owner from **ServiceNow by serial** (SQL cannot — a unit stores no XID of its own). See
+   *Null-contact backfill* below. Run **after** the dedup migration so the contact map is small.
+
+### Dedup migration (`2026-07-07 - Contact Dedup Merge.sql`)
+
+Keeper per `c_employeeXid` = **oldest NAMED contact with a primary email**, else oldest named,
+else oldest. Rows with blank/NULL XID are **excluded** so unrelated contacts never merge. Phases:
+
+1. Re-point the **16 columns** that reference `Contacts` to the keeper.
+2. **Re-point** `ContactEmailAddresses`/`ContactPhoneNumbers.contactId` to the keeper (instead of
+   deleting them). This resolves the `Contacts.primaryContactEmailAddressId` /
+   `primaryContactPhoneNumberId` back-reference **FK cycle** — `contactId` is non-unique on those
+   tables so no collision — and preserves every primary pointer.
+3. `ContactAddresses` has `UNIQUE(contactId, addressId)`, so it is **nulled then deleted**
+   (0 cross-links observed).
+4. Delete non-keeper bridge/detail rows that have no remaining back-reference.
+5. Delete non-keeper contacts via a **materialized double-nested subquery** (avoids MySQL
+   error 1093 "can't specify target table" on Contacts-targeting statements — the same idiom
+   documented in the dbchanges2 architecture doc).
+
+Uses inline keeper subqueries — **no work table, no backup table** (the DBA takes a DB backup
+separately). Sandbox result on a full prod copy: Contacts **893,379 → 19,754**; duplicate XIDs
+**3,820 → 0**; named contacts preserved; SalesOrders/ServiceRequests/PurchaseOrders/Units counts
+unchanged and zero now point to an empty contact; ContactEmailAddresses/PhoneNumbers preserved;
+zero dangling/orphaned references.
+
+### Null-contact backfill (`backfill_unit_contacts.php`)
+
+Resumable, unit-driven. For each `Unit` with `contactId` NULL it queries ServiceNow by serial
+(`/gbts/v1/sn_pcaas/asset?serial_number=`) for the owner XID, resolves the contact uuid (reusing
+the map logic), and PUTs `/units {serialNumber, contact:{uuid}}`. Resumable via a `Parameters`
+pointer key **`SERVICE_NOW_UNIT_CONTACT_BACKFILL`** (upserts; generates a uuid4 on insert),
+time-bounded per run.
+
+**Do NOT force NULL contactId to zero.** Null-contact units are frequently **legitimate**: Dell
+has not yet assigned the laptop to an employee, so the device is unassigned inventory (ServiceNow
+returns no `ownedBy`). Verified read-only on the prod copy: of **22,960** null-contact units, only
+**26** shipped on a Toga ASN (all 26 trace to a named order contact); the other ~22,934 never went
+through a Toga order and cluster in inventory dispositions/stages (only 15 "In Use"). **Caveat:**
+the device-import cron also pulls CMDB assets never ordered through Toga, so "not on an ASN" does
+not by itself prove unassigned — definitive ownership is **ServiceNow-by-serial only**. A residual
+of no-owner units after backfill is **expected and correct**.
+
+## Gotchas
+
+- **Never link a related record by a non-identifier custom field.** `c_employeeXid` is not a match
+  key; only `uuid` (or the numeric internal id) links an existing child. Passing the custom field
+  alone silently creates a new empty record on every write.
+- **Ordering is load-bearing:** deploy the cron fix → run the dedup migration → run the backfill.
+  Running dedup before the cron fix regenerates duplicates.
+- **No `continue`** in the helpers added to this cron (team standard); the new backfill file is
+  tab-indented (the legacy cron body is space-indented — only the added helpers were converted).
+- API auth uses the `App_Api_Toga2::CLIENT_UUID_PRUDENTIAL` / `API_UUID_PRUDENTIAL` /
+  `API_SECRET_PRUDENTIAL` constants (names only — values live in config, not here).
+
+## Change history
+
+- 2026-07-07 — Root-caused the "null null" export incident to nested `contact: {c_employeeXid}`
+  writes (~893k empty Contacts, ~23k NULL-contact Units, ~5,600 dupes/day). Fixed the cron to
+  build a `c_employeeXid → keeper uuid` map and send `contact: {uuid}` (deployed to prod). Built
+  the Contact dedup merge migration (tested on prod copy, not yet run) and a ServiceNow-by-serial
+  null-contact backfill cron (logic tested, not yet run). Confirmed NULL-contact units are often
+  legitimate unassigned inventory — do not force to zero. (bala)
+
+## Related docs
+
+- [Prudential profile](../profile.md)
+- [2.0 api2 — Nested-relationship writes & child matching](../../../2.0/apps/api2/features/nested-relationship-writes.md)
+  — the general api2 behavior this incident exposed.
+- dbchanges2 architecture — *Self-referencing DELETE* idiom used by the dedup migration.

package/knowledge/clients/prudential/profile.md

@@ -12,13 +12,14 @@ project: _Underscore
 client: prudential
 type: profile
 status: active
-updated: 2026-07-06
-owners: ["jcardinal", "rgirish"]
+updated: 2026-07-07
+owners: ["jcardinal", "rgirish", "bala"]
 files: []
 related:
   - features/dell-asn-units-interceptor.md
   - features/service-request-address-validation.md
   - features/dell-lch-iop-transmissions.md
+  - features/device-information-import-and-contact-linking.md
 ---
 
 ## Summary
@@ -60,3 +61,5 @@ order-status transmissions.
 - Dell LCH IOP transmissions (LCHRequestV2, outbound 1.0).
 - 2.0 _underscore: Tracking-Number Bridge Migration.
 - features/transmit-ordershipped-email.md
+- features/device-information-import-and-contact-linking.md — device-sync cron, unit→contact
+  linking, the "null null" contact-export incident + dedup/backfill remediation.

package/knowledge/clients/rate/INDEX.md

@@ -8,4 +8,5 @@
 | [Rate SAML SSO](features/saml-sso.md) | 2.0 | Rate uses Azure AD as its IdP (`login.rate.com`). | _underscore/Model/Rate/ClientAuthentication.php, saml/Controller/Index.php, toga2-view/src/hooks/useAuthenticationFlow.ts |
 | [Service Card Entitlement Display](features/service-card-entitlements.md) | 2.0 | Rate's home and services pages display one service card per purchased entitlement. | src/components/ServiceCard/ServiceCard.tsx, src/components/ServiceCard/index.ts, src/hooks/useBundleServices.ts, src/pages/Home/api/homeApi.ts, src/pages/Home/view/HomePage.tsx, src/pages/Home/viewModels/useHomePageViewModel.ts, src/pages/Services/view/ServicesPage.tsx, src/pages/Services/viewModels/useServicePageViewModel.ts |
 | [Rate Service-Purchase Confirmation Emails (Tech / Warranty)](features/service-purchase-emails.md) | 2.0 | When a Rate customer purchases a service, a confirmation email is sent. | _underscore/Model/Rate/Entitlement.php, worker2/Worker/Notification/EmailTemplate.php, dbchanges2/Client_Rate/2026-06-30a - Rate purchase email templates.sql |
+| [Rate Whole Home Warranty Per-Address Purchase Guard](features/whole-home-warranty-purchase-guard.md) | 2.0 | A customer may hold **one active Whole Home Warranty (WH) per validated address, globally** (across all borrowers). | _underscore/Model/Rate/Entitlement.php, _underscore/Model/Client/Address.php, dbchanges2/Client_Rate/2026-07-07a - WholeHomeWarrantyPerAddressGuard.sql |
 | [Rate](profile.md) | 2.0 | Rate is a mortgage/lending client. |  |

package/knowledge/clients/rate/features/aig-contract-creation.md

@@ -14,6 +14,7 @@ files:
   - worker2/Worker/Monitors/RateEntitlement.php
 related:
   - clients/rate/profile.md
+  - clients/rate/features/whole-home-warranty-purchase-guard.md
   - ../../../2.0/apps/worker2/features/monitoring-framework.md
 ---
 
@@ -35,6 +36,13 @@ This is a base-`_underscore` interceptor specific to Rate's product (it lives un
 `Model/Rate/`); documented here as a Rate client-feature because the behavior and its
 monitoring are Rate-scoped.
 
+**As of 2026-07-07 (TRUE-79533)** the same `postPost` also persists the validated **service
+address** (`Entitlements.c_serviceAddressId`, `Addresses.isValidated=1`) — that persistence is
+wrapped so it never blocks this AIG-contract flow or the confirmation email. For Whole Home
+Warranty purchases, a new `prePost` guard now also **carrier-normalizes the address onto the
+payload before save**, so the AIG contract is created with the canonical address. See the
+[Whole Home Warranty per-address purchase guard](whole-home-warranty-purchase-guard.md).
+
 ## How it works
 
 1. `postPost` runs after an entitlement is saved. It proceeds **only if** the payload has a
@@ -91,6 +99,10 @@ creation vs. cancellation. This is an accepted, documented limitation — not an
 
 ## Change history
 
+- 2026-07-07 — `postPost` now also persists the validated service address
+  (`Entitlements.c_serviceAddressId`, `Addresses.isValidated=1`), wrapped so it never blocks the
+  AIG-contract/email flow; a new WH `prePost` guard carrier-normalizes the address onto the
+  payload before save (TRUE-79533). See the WH per-address purchase guard doc. (mhammontree)
 - 2026-06-29 — Documented the silent-failure AIG warranty-contract interceptor and the
   external log-scan monitor (`_Worker_Monitors_RateEntitlement`, TRUE-79129), including the
   accepted detection limitation that auth-induced failures are not attributable (shared

package/knowledge/clients/rate/features/whole-home-warranty-purchase-guard.md

@@ -0,0 +1,140 @@
+---
+title: "Rate Whole Home Warranty Per-Address Purchase Guard"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: rate
+type: client-feature
+status: active
+updated: 2026-07-07
+owners: [mhammontree]
+files:
+  - _underscore/Model/Rate/Entitlement.php
+  - _underscore/Model/Client/Address.php
+  - dbchanges2/Client_Rate/2026-07-07a - WholeHomeWarrantyPerAddressGuard.sql
+related:
+  - clients/rate/profile.md
+  - clients/rate/features/aig-contract-creation.md
+  - ../../../2.0/apps/_underscore/features/address-validation.md
+---
+
+## Summary
+
+A customer may hold **one active Whole Home Warranty (WH) per validated address, globally**
+(across all borrowers). This guard enforces that business rule at purchase time on the Rate
+Entitlements route via a `prePost` interceptor on `_Model_Rate_Entitlement`
+(`_underscore/Model/Rate/Entitlement.php`, Core.Records recordId **191**, registered PRE/POST).
+
+For **WH purchases only** (WH is identified by the sale-item title containing `"warranty"`,
+consistent with `resolvePurchaseProduct`), the guard:
+
+1. **Requires a service address** from `$payload->contact->primaryContactAddress->address`.
+2. **Hard-blocks** the purchase if
+   [`_Model_Client_Address::validateAddress`](../../../2.0/apps/_underscore/features/address-validation.md)
+   (USPS→FedEx→UPS waterfall) returns `success:false` — no entitlement is created; the error
+   surfaces to the frontend toaster.
+3. **Adopts the carrier-normalized address** (`address1`/`address2`/`city`/`state`/`zipCode`)
+   and writes it back onto the payload, so both the saved address and the AIG contract use the
+   canonical form.
+4. **Hard-blocks a second active WH at the same physical address globally** via
+   `hasActiveWarrantyAtAddress()`.
+
+`postPost` then persists the validated service address after save (sets `Addresses.isValidated=1`
+and `Entitlements.c_serviceAddressId`), wrapped so it never blocks the existing AIG-contract /
+confirmation-email flow.
+
+Ticket: TRUE-79533. Business rule owner: PM Paulina.
+
+## Business rules (decided this session — Mark / Paulina)
+
+- **Invalid address → HARD BLOCK.** An address that fails carrier validation blocks the
+  purchase entirely (no entitlement), surfaced as an API error to the frontend toaster.
+- **Uniqueness is GLOBAL per address**, not per-borrower — a second active WH on the same
+  physical address is rejected regardless of which borrower buys it.
+- **Address line2 distinguishes units.** A landlord's apartment units are distinct addresses:
+  2A / 2B / 2C = three separate WHs. Uniqueness keys on the full normalized address including
+  line2.
+- **Persist the validated address ON the entitlement** (new `c_serviceAddressId` FK) rather
+  than deriving it from the fragile contact-primary-address path, and **backfill** existing WH
+  entitlements so the global rule covers production data already present.
+
+## How it works
+
+1. **`prePost` (PRE/POST interceptor).** Fires only for WH sale items (title LIKE
+   `%warranty%`).
+2. Reads the service address off `$payload->contact->primaryContactAddress->address`; missing
+   address → block.
+3. Calls `_Model_Client_Address::validateAddress`; `success:false` → block. On success, copies
+   the normalized `address1/address2/city/state/zipCode` back onto the payload.
+4. `hasActiveWarrantyAtAddress()` joins `Entitlements` → `Items` (title LIKE `%warranty%`, with
+   WH `Items.id = 3` as an OR fallback) → **active** `Subscriptions` (`isActive = 1 AND
+   dateCancelled IS NULL`) → `Addresses` on the new `c_serviceAddressId` column. A match → block
+   the second active WH.
+   - **The dedup read disables the query cache** (`_Database::useQueryCache(false)`, restored in
+     a `finally`) so it sees rows committed by a just-prior purchase rather than a stale cached
+     result set.
+5. **`postPost`.** After save, persists the validated service address: sets
+   `Addresses.isValidated = 1` and writes `Entitlements.c_serviceAddressId`. This block is
+   wrapped so a failure never interrupts the AIG-contract creation or the confirmation email
+   (see the [AIG contract creation doc](aig-contract-creation.md) — the same `postPost`).
+6. All SQL uses `_Database::escape()` / int-casts — `_Query` has **no bind API** in this path.
+
+## Migration (`dbchanges2/Client_Rate/2026-07-07a - WholeHomeWarrantyPerAddressGuard.sql`)
+
+- Adds `Entitlements.c_serviceAddressId INT NULL` + an index.
+- Guarded (`NOT EXISTS`) registration of `CustomRecordFields` for `c_serviceAddressId`
+  (recordId 191, type **NUMBER**).
+- Guarded registration of the `ApiPayloadInterceptors` PRE/POST rows.
+- A one-time, idempotent backfill of `c_serviceAddressId` for existing WH entitlements, sourced
+  from `Contacts` → `ContactAddresses` → `Addresses`.
+
+## Rate data model (prod-verified 2026-07-07)
+
+- **WH product** = `Items.id 3` / `partNumber 1429124` "Whole Home Warranty - Monthly". Tech
+  products are `Items.id` 1 and 2.
+- **Active-subscription signal is on `Subscriptions`** (`isActive` tinyint default 1,
+  `dateCancelled`, `dateEnd`, `dtRequestToCancel`). `Entitlements` has **no `isActive`**.
+- **Entitlements had no address linkage before this ticket.** `SalesOrders` has
+  `shipToAddressId`/`billToAddressId` but they are NULL for Rate. Before `c_serviceAddressId`,
+  the address was reachable only via `Entitlement.contactId` → `Contacts.primaryContactAddressId`
+  → `ContactAddresses.addressId` → `Addresses`.
+- **Borrower identity** = `Customers.c_borrowerId`.
+- **Core.Records record IDs:** Addresses = 13, Entitlements = 191, Sales orders = 14,
+  Entitlement tickets = 212.
+
+## Frontend contract (delivered by Tanner — TRUE-79825 / 79969 / 79905, toga2-view)
+
+The frontend UI that this guard honors was delivered separately: `components/ValidateAddressModal`,
+`hooks/useValidateAddressFormViewModel`, `pages/ZipValidation`. The FE calls
+`GET /addresses/validateAddress` and reads **`data.addresses.validateAddress`** typed as
+`{ success, error?, address1?, address2?, city?, state?, zipCode?, country? }`. The modal shows
+suggested-vs-entered when `success && address1`, and a "couldn't verify" toaster when
+`success === false`. See the shared
+[address-validation feature](../../../2.0/apps/_underscore/features/address-validation.md) for the
+endpoint mechanics.
+
+## Gotchas / known issues
+
+- **TOCTOU on the uniqueness check (accepted).** The check-then-persist dedup is **not**
+  lock-guarded. Two truly concurrent same-address WH purchases could both pass. Accepted for
+  sequential purchases; documented in code.
+- **AIG carrier vs. AIG tenant.** "AIG" here is the warranty **carrier** behind Rate's Whole
+  Home Warranty — a different codepath from the separate `Client_Aig` / Staples Protection Plan
+  tenant. Do not conflate the two.
+- **`ApiPayloadInterceptors` (Client_Rate) has no `phpMethod` column.** The interceptor method
+  is resolved **by convention** from `(prePostProcessing, httpMethod)`: `PRE+POST → prePost`,
+  `POST+POST → postPost` (matches the framework `[pre|post][HttpMethod]` convention).
+- **`CustomRecordFields.type` enum supports only `STRING`/`NUMBER`** — `c_serviceAddressId` is
+  registered as `NUMBER`.
+- **No `_Query` bind API here** — use `_Database::escape()` / int-casts for all interpolated
+  values.
+
+## Change history
+
+- 2026-07-07 — Built the WH per-address purchase guard (TRUE-79533): `prePost` on
+  `_Model_Rate_Entitlement` hard-blocks invalid addresses and second active WH at the same
+  normalized address (global), adopts the carrier-normalized address onto the payload, and
+  disables the query cache for the committed-read dedup; `postPost` persists the validated
+  service address (`Entitlements.c_serviceAddressId`, `Addresses.isValidated=1`) without blocking
+  the AIG/email flow. Migration adds `c_serviceAddressId` + index, registers the CustomRecordField
+  and PRE/POST interceptors, and backfills existing WH entitlements. (mhammontree)

package/package.json

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