toga-ai 1.0.484 → 1.0.485

package/knowledge/sessions/2026-07-30-TRUE-80487-Debug-Fix-Rate-WH-Warranty-mhammontree.md

@@ -0,0 +1,97 @@
+---
+type: session
+slug: TRUE-80487-Debug-Fix-Rate-WH-Warranty
+title: Rate Whole Home Warranty per-address dedup — root-caused "works in beta, fails in prod"
+author: mhammontree
+repos: [_underscore, toga2-view, dbchanges2, test]
+framework: "2.0"
+client: rate
+status: active
+created: 2026-07-30
+updated: 2026-07-30
+---
+
+# Session: TRUE-80487-Debug-Fix-Rate-WH-Warranty
+**Date:** 2026-07-30
+**Project/Repo:** _underscore / toga2-view / dbchanges2 / test (2.0)
+**Task:** Production troubleshooting of the Rate Whole Home Warranty per-address duplicate-purchase guard (TRUE-79533, already deployed), reported as "works in beta, not in production" — root-caused to three independent code defects, none of them a deployment gap.
+
+---
+
+## What WORKED
+
+- **Eliminated every deployment-gap hypothesis with hard evidence.** `_underscore` `_production` HEAD is `ba7eff66` (TRUE-79533 PR #661 merged 2026-07-29); `dbchanges2` `_main` is `138df5e` (PR #418). `git diff origin/_beta -- Model/Rate/Entitlement.php` returns **zero diff** — prod and beta run identical code.
+- **Confirmed all prod DB artifacts present.** `Core.RecordFields` id **2482** = `entitlements.serviceAddressId` registered; `Client_Rate.Entitlements.serviceAddressId` column + index exist; ACL grants present (`2482` → role 1 `isWritable=0`, mirroring `saleItemId` 1265; `addresses.id` field 41 → roles 1,2,3). `ApiPayloadInterceptors` in prod is **byte-identical to dev-sandbox** (id 4 = rec 191 PRE/POST `minDepth NULL`; id 2 = rec 191 POST/POST `minDepth 5`).
+- **ROOT CAUSE #1 — the backend guard has never executed, in any environment.** `isWholeHomeWarranty()` at `_underscore/Model/Rate/Entitlement.php:116-118` reads `$payload->saleItem->title`, but the real checkout payload sends `"saleItem":{"uuid":"3e14effa-0f78-4708-b338-60872a39aff3"}` with **no `title`**. `stripos('', 'warranty')` → false → `prePost` returns at line 58 before the guard runs. Evidence: beta payload for entitlement 106, `Logs_Rate.Api` id 48823 (dev-sandbox, 2026-07-27 11:41:15), verbatim.
+- **Proved it with beta's own data.** dev-sandbox has **three active WH entitlements at the same address** `1864 HIGH GROVE LN 60540`: `ET100057` (id 90, 2026-07-24), `ET100067` (id 100, **2026-07-27 10:10**), `ET100073` (id 106, **2026-07-27 11:41**) — two created on the very day the feature was marked "beta-verified". Plus two at `121 N LA SALLE ST 60602` (`ET100071`, `ET100072`). All same borrower `5686507f-a7b2-4fca-b007-dd3ae875e4bb`, all pinned, all active.
+- **Confirmed the guard's rejection message appears in NO log, in either environment, ever.** All 8 beta `POST /v2/entitlements` 400s are `EV-12` (reference errors) and one `EV-8` (`contractFulfillmentPreference`, 2026-07-15, pre-dating the PRE interceptor registration).
+- **ROOT CAUSE #2 — `state.code` vs `state.uuid`.** `prePost:66` reads `$address->state->code`, but the payload sends `"state":{"uuid":"94417b26-..."}`. Fixing #1 alone would make every WH purchase throw *"A valid service address is required"* — a false rejection on valid addresses. **Both must be fixed together.**
+- **ROOT CAUSE #3 — frontend availability check fails open AND is borrower-scoped.** `toga2-view/src/pages/ZipValidation/viewModels/useZipValidationViewModel.ts:135-139` — `const address = entitlement.serviceAddress; if (!address?.line1) return false;` and `serviceAddress` is derived only from the pin (`useActiveServices.ts:108`). Worse, `useActiveServices.ts:69-71` scopes the query `where: { and: [{ "Customers.c_borrowerId": { "=": borrowerId } }] }` — so it can **never** see another borrower's warranty, while the backend guard is explicitly global. Its code comment claims "same source as the backend guard's dedup join" — that comment is wrong; the backend uses `COALESCE(serviceAddressId, ContactAddresses.addressId)`, the frontend has no fallback.
+- **Verified the backend WOULD block, without paying.** Replicated `hasActiveWarrantyAtAddress()` SQL read-only against prod for `1864 HIGH GROVE LN / Naperville / 60540 / IL` → returns entitlement **43 (`ET100017`)**. So a real purchase reaches PayPal, the customer is charged, and *then* the entitlement POST is rejected.
+- **Confirmed the apartment-building exposure is real.** Property type lives only in router state / `sessionStorage` (`useCheckoutPageViewModel.ts:178-205`) and is **never sent to the API** — the purchase payload contains no `propertyType` / `isEligible`. `prePost:68-70` requires line1/city/state/zip but **not** `line2`. The `requireUnitNumber` flow (`ZipValidation.tsx:62-75`, `198-199`) is client-side only and bypassable. Live proof: beta `ET100073` carries `line2: "STE 500"` on a single-family home, while ids 90/100 at the same `line1` have no unit.
+- **Production data repaired by the developer and verified clean.** Three active WH warranties, all pinned + validated, both-or-neither invariant holds on all nine rows: 43 (`ET100017`) → addr 9 Naperville, 40 (`ET100014`) → addr 6 Nashua, 38 (`ET100012`) → addr 4 Wailuku. Subscription 22 (`ET100015`, Daniel Moran) closed out `isActive=0, dateCancelled='2026-06-03'`; address 7 `city` corrected `60657` → `Chicago`.
+
+## What did NOT work — DO NOT RETRY THESE
+
+- **"A migration is missing in production."** DISPROVEN. `Core.RecordFields` 2482 exists; `Client_Rate.Entitlements.serviceAddressId` column + index exist; both ACL grants landed. Do not re-audit `Core/2026-07-22a`, `Client/2026-07-22a`, `Client/2026-07-23a`, `Client_Rate/2026-07-23a`, `Client_Rate/2026-07-24a` — all applied.
+- **"TRUE-79251 merge damage deleted the WH helper methods."** DISPROVEN. `git diff origin/_beta -- Model/Rate/Entitlement.php` → zero diff. `PASSTHROUGH_KEY_FULFILLMENT_PREFERENCE` (line 32) and all three private helpers (`normalizedField` 107, `isWholeHomeWarranty` 116, `hasActiveWarrantyAtAddress` 137) present.
+- **"`_underscore` prod wasn't redeployed past the uuid-clobber fix `9c2e4b1c`."** DISPROVEN by the same zero diff + PR #661 merged.
+- **"`toga2-view` prod still sends `{depth:-1}` and starves `postPost`."** DISPROVEN. `genericApi.ts:54,68` only append `?depth=-1` when `returnPayloadDepth` is explicitly set; no checkout override. Diff vs `_beta` touches only GetSupport files.
+- **"Cross-cluster `Core.RecordFields` references from `Client*/` migration folders fail in prod."** DISPROVEN for this case. Despite prod splitting `prod-core` / `prod-client` / `prod-logs` / `prod-archive` onto separate clusters, the ACL grants landed correctly. ~20 long-standing ACL migrations use this same pattern. (Note: the `dbchanges2-cluster-isolation` hook was NOT found under `.claude/hooks/toga/` — separate follow-up, not this bug.)
+- **"The interceptor row is missing, inactive, or duplicated in prod."** DISPROVEN — prod rows are identical to dev-sandbox, same ids and uuids.
+- **"`POST /v2/entitlement-sales-orders` is the prod purchase path (record 257, no interceptor)."** DISPROVEN. It is only a bridge link: payload is `{"entitlement":{"uuid"},"salesOrder":{"uuid"}}`. It creates no entitlement and fires no interceptor.
+- **"Production simply hasn't processed a purchase since deploy, so there's nothing to debug."** TRUE as a fact (last `POST /v2/entitlements` in prod = 2026-07-10, two × 400 `EV-8`; newest `Entitlements` row 2026-06-15) but WRONG as a conclusion — the developer then reproduced the failure live through the UI. Do not stop at this observation.
+- **Query that hangs — do not run.** `SELECT ... FROM Logs_Rate.Api WHERE route LIKE '%address%'` timed out after **300s** (unindexed full scan on a ~12.7M-row table). Always constrain with the `dtStamp` index: `WHERE dtStamp >= '...' AND dtStamp < '...'`.
+- **Columns that do not exist (queries will error).** `Client_Rate.ApiPayloadInterceptors.phpMethod` — absent in prod (yet `Client_Rate/2025-12-10 - PostInterceptor.sql` inserts it, so that file is not re-runnable). `Client_Rate.Contacts.emailAddress` — does not exist. `Logs_Rate.Api.uri` — the column is `route`.
+- **Widening the frontend `useActiveServices` query to all borrowers.** REJECTED, do not do this — it would let any portal user read other customers' entitlements and addresses. A data-leak fix worse than the bug.
+
+## Not tried yet (candidates for next session)
+
+- Fix `isWholeHomeWarranty()` to resolve `saleItem.uuid` → item (fall back to payload `name` and/or `WH_SALE_ITEM_ID = 3`), matching the authority `hasActiveWarrantyAtAddress()` already uses in SQL.
+- Fix state resolution to accept `state.uuid` with `state.code` as fallback.
+- Normalize zip to first 5 digits in the dedup comparison (`Entitlement.php:161` is exact-match; frontend already truncates at `addressCompare.ts:22`). Untested risk: USPS returning `60540-9233` vs stored `60540`.
+- Normalize the unit designator before comparison so `STE 500` / `Suite 500` / `#500` / `Unit 500` collapse to one dwelling.
+- Build the server-side global pre-check: boolean-only scripted endpoint reusing `hasActiveWarrantyAtAddress()`, called from the availability step, deleting the frontend's local dedup. Needs a `dbchanges2` migration registering it in `Core.RecordScripts` **plus** the client ACL grant — note `validateAddress` (RecordScripts id 17) exists only in the live DB and NOT in `dbchanges2`, the exact parity trap to avoid.
+- Log one raw USPS / FedEx / UPS validation response for a known apartment vs a known single-family address, to settle field names empirically. `Fedex.php:417-421` already receives the full `attributes` object and reads only `Matched` / `Resolved`; `Ups.php:801-807` reads only `NoCandidatesIndicator` / `Candidate`.
+- Capture the USPS DPV "valid but secondary unit missing" signal into `validateAddress`'s normalized return with an explicit unknown state, and enforce in `prePost`.
+- Send and persist `propertyType` with the purchase so eligibility is enforced server-side rather than trusted from the browser.
+- Update `test/@Mark/Rate/verify_wholehome_per_address_guard.php` to use the REAL payload shape (uuid-only `saleItem`, uuid-only `state`). It currently passes 18/18 against a shape production never sends — this is why all three defects survived review.
+- Clean up beta duplicates: dev-sandbox entitlements 100, 105, 106.
+- Controlled prod WH purchase to exercise the untested `minDepth = 5` on the POST interceptor, and to test USPS "Suggested" (`60540-9233`) vs "You entered" (`60540`).
+
+## Current file state
+
+| File | Status | Notes |
+|------|--------|-------|
+| `_underscore/Model/Rate/Entitlement.php` | **investigated, NOT modified** | Holds root causes #1 (line 116-118) and #2 (line 66). Also: raw SQL string concatenation at lines 371/375 violates the parameterized-query standard; accepted TOCTOU noted at 133-135. |
+| `toga2-view/src/pages/ZipValidation/viewModels/useZipValidationViewModel.ts` | **investigated, NOT modified** | Root cause #3 fail-open at 135-139. Misleading comment claims parity with backend join. |
+| `toga2-view/src/hooks/useActiveServices.ts` | **investigated, NOT modified** | Borrower-scoped `where` at 69-71; pin-only `serviceAddress` resolution at 108; silent EZ-2 degrade at 90. |
+| `toga2-view/src/pages/CheckOut/viewModel/useCheckoutPageViewModel.ts` | **investigated, NOT modified** | `propertyType` read from router state / sessionStorage (178-205), never sent to API. |
+| `_underscore/Model/Client/Address.php` | **investigated, NOT modified** | `validateAddress` waterfall USPS→FedEx→UPS (31-46); returns success + normalized fields only, no unit-required signal. |
+| `_underscore/Component/Library/Carriers/{Usps,Fedex,Ups}` | **investigated, NOT modified** | Signals available but discarded. NOTE: this is a namespace inside `_underscore`, NOT the 1.0 `library` repo. |
+| `test/@Mark/Rate/verify_wholehome_per_address_guard.php` | **not opened** | Passes 18/18 against the wrong payload shape. Needs rewrite. |
+| **Production `Client_Rate` data** | **CHANGED by developer, verified** | Ents 43→addr 9, 40→addr 6, 38→addr 4 pinned; those 3 addresses `isValidated=1`; subscription 22 closed `isActive=0, dateCancelled='2026-06-03'`; address 7 `city` → `Chicago`. No repo files changed this session. |
+
+## Decisions made
+
+- **Keep `dateEnd` OUT of the dedup predicate.** Rationale: the guard's contract is `isActive = 1 AND dateCancelled IS NULL`; adding `dateEnd` would let real duplicates through when a renewal hasn't rolled `dateEnd` forward yet. Rejected alternative: filter on `dateEnd`. Confirmed instance of the underlying problem: Kimberly Stearns (`ET100014`) has `dateEnd = 2026-06-01` yet was charged 2026-07-01 — renewals are not advancing `dateEnd`. **Separate ticket.**
+- **Do NOT widen the frontend query to all borrowers; move the check server-side instead.** Rationale: the frontend fundamentally cannot answer "does anyone have a warranty here?" without exposing other customers' data. A boolean-only endpoint reusing the existing helper makes availability and purchase the same code path, so they cannot drift.
+- **Skip the legacy-entitlement backfill migration.** Rationale: only two rows mattered and they were fixed by hand; once the server-side check ships, pinning is no longer required for dedup correctness. Migration would be pure data churn.
+- **Do not chase "dwelling type" from shipping carriers.** Rationale: postal data models deliverability, not property characteristics — no carrier returns single-family vs multi-unit. UPS `AddressClassification` / FedEx `classification` only give Residential vs Commercial, and an apartment building is "Residential". The actionable signal is USPS DPV "secondary unit required but missing". True dwelling type needs property data (assessor/parcel, or Melissa/Smarty-class vendor) — a procurement decision for Paulina + underwriting.
+- **Did NOT complete the PayPal test payment.** Rationale: the backend rejects *after* the charge; the read-only SQL replication already proved what the guard decides.
+- **Branch naming = bare ticket ID `TRUE-80487`.** Rationale: matches live convention in all four repos (`TRUE-78188`, `TRUE-78314`, `TRUE-79191`, `TRUE-79868`). The documented `fix/short-description` rule in the git-workflow standard is stale — flag for correction.
+- **Repo scope:** minimum `_underscore` + `test` (makes the global rejection actually work); add `dbchanges2` + `toga2-view` for the server-side pre-check. `api2` NOT needed (scripted endpoints are served by the V2 engine from `_underscore` models; registration is DB-side). Recommendation: branch all four — an unused branch is free, discovering a needed migration mid-sprint is not.
+- **Reframed the ticket premise.** "Works in beta, fails in prod" is false. Same code, same migrations, same interceptor rows. Beta only *appeared* to work because its test data satisfied both frontend preconditions by accident — a single test borrower, and data created after the pin shipped. Production satisfied neither.
+
+## Blockers
+
+- **Need the current dev branch name** to base the four `TRUE-80487` branches on. `_underscore` shows `_beta`; `toga2-view` shows both `_beta` and `_stage`. Developer said they are on "a different dev branch now" — unresolved.
+- **Need a product decision from Paulina: per-dwelling or per-building coverage?** Currently `123 Main St` and `123 Main St APT 2` are distinct addresses, so both can hold a warranty. This changes what the fix does. Sharpened by the finding that a *no-unit* purchase at a multi-unit address is indistinguishable from a single-family purchase and carries building-scale liability at single-home pricing.
+- **Need a scope decision:** does property-type / unit-required enforcement land in TRUE-80487, or a separate ticket? Materially larger than "one warranty per address" — it is "what counts as an insurable address". The gate fixes are independent of both blockers and can proceed regardless.
+
+## Exact next step
+
+> Create the `TRUE-80487` branch on `_underscore` (base = the dev branch the developer names), then fix `isWholeHomeWarranty()` at `_underscore/Model/Rate/Entitlement.php:116-118` to identify a WH purchase by resolving `saleItem.uuid` → `Items` (with payload `name` / `WH_SALE_ITEM_ID = 3` as fallbacks) **together with** the `state.uuid` → `code` resolution at line 66 — never one without the other, or every WH purchase throws "A valid service address is required". Then run `test/@Mark/Rate/verify_wholehome_per_address_guard.php` rewritten to the real payload shape (uuid-only `saleItem` and `state`), and confirm it FAILS on the current code before the fix and passes after.
+
+---
+_Saved by /session-save on 2026-07-30_

package/package.json

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