toga-ai 1.0.368 → 1.0.369

package/knowledge/clients/rate/INDEX.md

@@ -8,5 +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, test/@Mark/Rate/verify_wholehome_per_address_guard.php |
+| [Rate Whole Home Warranty Per-Address Purchase Guard](features/whole-home-warranty-purchase-guard.md) | 2.0 | > **⚠ NOT IN PRODUCTION (as of 2026-07-17).** TRUE-79533 is **not** merged to `_production`. | _underscore/Model/Rate/Entitlement.php, _underscore/Model/Client/Address.php, dbchanges2/Client_Rate/2026-07-07a - WholeHomeWarrantyPerAddressGuard.sql, test/@Mark/Rate/verify_wholehome_per_address_guard.php |
 | [Rate](profile.md) | 2.0 | Rate is a mortgage/lending client. |  |

package/knowledge/clients/rate/features/service-purchase-emails.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: rate
 type: client-feature
 status: active
-updated: 2026-06-30
+updated: 2026-07-17
 owners: [mhammontree]
 files:
   - _underscore/Model/Rate/Entitlement.php
@@ -118,6 +118,15 @@ Email web-font reality: Gmail/Outlook strip web fonts and fall back; Apple Mail/
 
 ## Gotchas / known issues
 
+- **Shared interceptor with TRUE-79533 (WH per-address guard) — same `prePost`/`postPost`.** This
+  workflow's `postPost` trigger + helpers live in the **same** `_Model_Rate_Entitlement`
+  interceptors that the [Whole Home Warranty per-address guard](whole-home-warranty-purchase-guard.md)
+  edits, and TRUE-79251 also adds the passThrough `const PASSTHROUGH_KEY_FULFILLMENT_PREFERENCE` +
+  the contractFulfillmentPreference (EV-8) fix inside `prePost`. A bad `_production`→`_beta` merge
+  already mis-resolved this once and fatally broke every Rate purchase save. When merging either
+  ticket across branches, hand-merge into ONE `prePost()` keeping both features' logic — see the
+  **shared-interceptor merge hazard** gotcha on that doc for the correct resolution and why `php -l`
+  is not a sufficient gate.
 - **`border-radius` on a `<td>` renders SQUARE in many clients (Outlook).** Use an `<img>` for
   circular badges/icons (e.g. the green circle-check) instead of a CSS-rounded table cell.
 - **ASCII-only subjects (mojibake workaround).** `_Email::send()` does not set PHPMailer
@@ -150,6 +159,9 @@ Remaining items are **optional / separate, not go-live blockers**:
 
 ## Change history
 
+- 2026-07-17 — Added a cross-reference to the [WH per-address guard](whole-home-warranty-purchase-guard.md):
+  both tickets edit the same `_Model_Rate_Entitlement` `prePost`/`postPost` interceptors, a
+  shared-interceptor merge hazard that already broke `_beta` once. No behavior change here. (mhammontree)
 - 2026-06-30 — Built the Rate service-purchase confirmation email workflow (TRUE-79251):
   `postPost` trigger + helpers in `_Model_Rate_Entitlement`, two DB-stored `Client_Rate`
   templates (tech / warranty) dispatched off-thread via

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

@@ -5,8 +5,8 @@ repo: _underscore
 project: _Underscore
 client: rate
 type: client-feature
-status: active
-updated: 2026-07-08
+status: draft
+updated: 2026-07-17
 owners: [mhammontree]
 files:
   - _underscore/Model/Rate/Entitlement.php
@@ -19,6 +19,13 @@ related:
   - ../../../2.0/apps/_underscore/features/address-validation.md
 ---
 
+> **⚠ NOT IN PRODUCTION (as of 2026-07-17).** TRUE-79533 is **not** merged to `_production`.
+> Its `_underscore` + `dbchanges2` PRs are still OPEN / "BACK-END REVIEW" (git-verified: commit
+> `be5002f4` is contained only in branches `TRUE-79533` and `_beta`, never `_production`). An
+> earlier belief that it "shipped weeks ago" is incorrect — TRUE-79251 (purchase emails) shipped,
+> this guard did not. The branch is being caught up to `_production` now. See the
+> **shared-interceptor merge hazard** gotcha below before merging.
+
 ## Summary
 
 A customer may hold **one active Whole Home Warranty (WH) per validated address, globally**
@@ -127,6 +134,36 @@ live carrier waterfall is opt-in via `RUN_LIVE=1` (defaults off). Verified **18/
 
 ## Gotchas / known issues
 
+- **Shared-interceptor merge hazard — TRUE-79533 and TRUE-79251 edit the SAME methods.** Both
+  this guard and the [purchase-email workflow](service-purchase-emails.md) (TRUE-79251) modify the
+  **same** `prePost`/`postPost` interceptors on `_Model_Rate_Entitlement`, and TRUE-79251 also adds
+  the passThrough `const PASSTHROUGH_KEY_FULFILLMENT_PREFERENCE` + the contractFulfillmentPreference
+  (EV-8) fix inside `prePost`. This makes the file a merge landmine:
+  - **What already went wrong (on `_beta`):** a later `Merge branch '_production' into _beta`
+    mis-resolved the conflict — it reverted `prePost` to production's version and **deleted** the
+    private helpers `isWholeHomeWarranty()`, `normalizedField()`, `hasActiveWarrantyAtAddress()`,
+    while leaving the caller `persistWarrantyServiceAddress()` (a separate hunk). Result:
+    `postPost` → `persistWarrantyServiceAddress()` → `self::isWholeHomeWarranty()` = fatal
+    `Error: Call to undefined method`, thrown **before** the method's own try/catch (so it is NOT
+    swallowed). This breaks the entitlement save for **every** Rate purchase (tech + warranty).
+    Because the crash happens **after** `sendPurchaseEmail()` was enqueued and the record saved, the
+    symptom is: record created + email sent, yet the API returns an error → user retries →
+    **duplicate entitlements / emails / AIG contracts**.
+  - **Correct conflict resolution is NEITHER side alone, and NOT "accept both".** The conflict is a
+    single block where HEAD (TRUE-79533) defines the WH-guard `prePost()` + 3 helpers and
+    `_production` defines the passThrough `prePost()` + `PASSTHROUGH_KEY_FULFILLMENT_PREFERENCE`.
+    Both sides define `prePost()`. accept-HEAD drops the constant (→ undefined-constant fatal in
+    `postPost`, and regresses the EV-8 contractFulfillment fix); accept-theirs reproduces the
+    `isWholeHomeWarranty` undefined-method crash; accept-both yields a fatal duplicate `prePost()`
+    redeclare. **Hand-merge into ONE `prePost()`** that (1) strips `contractFulfillmentPreference`
+    → `$api->passThrough` for every purchase, then (2) runs the WH guard for warranty purchases —
+    keeping the constant AND all three private helpers. The common `postPost` below the conflict
+    references **both** symbols (the constant at the AIG-contract build, and `isWholeHomeWarranty()`
+    in `persistWarrantyServiceAddress`), so both must survive.
+  - **`php -l` is NOT a sufficient gate here.** Lint passes on the broken accept-HEAD state — the
+    two failures (undefined class constant, EV-8 regression) are runtime, not syntax. Verify with
+    `test/@Mark/Rate/verify_wholehome_per_address_guard.php` (18/18 against `Client_Rate`,
+    carrier calls off).
 - **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.
@@ -143,6 +180,13 @@ live carrier waterfall is opt-in via `RUN_LIVE=1` (defaults off). Verified **18/
 
 ## Change history
 
+- 2026-07-17 — **Status corrected to `draft` / not-in-production** (TRUE-79533): git-verified the
+  guard was never merged to `_production` (PRs open / back-end review), contrary to a belief it had
+  shipped. Documented the **shared-interceptor merge hazard** with TRUE-79251 and the correct
+  hand-merge of the dual `prePost()` — a bad `_production`→`_beta` merge had deleted the WH helpers
+  (`isWholeHomeWarranty()` et al.) while keeping the caller, fatally breaking every Rate purchase
+  save and causing duplicate entitlements/emails/AIG contracts. Resolved the catch-up merge;
+  `php -l` clean and 18/18 verify against `Client_Rate`. (mhammontree)
 - 2026-07-08 — Added a backend verification script
   (`test/@Mark/Rate/verify_wholehome_per_address_guard.php`, 18/18 pass against the migrated
   `Client_Rate` schema) and a Verification pointer. (mhammontree)

package/package.json

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