toga-ai 1.0.283 → 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/INDEX.md

@@ -17,7 +17,7 @@ _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) — 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)

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.283",
+  "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",