toga-ai 1.0.424 → 1.0.425

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/hooks/useActiveServices.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, src/api/serviceAddressApi.ts, src/api/apiErrors.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 | > **⚠ DEPLOYING beta→production, NOT YET PROD-VERIFIED (as of 2026-07-23).** TRUE-79533 is > beta-verified (PM Paulina tested the WH purchase flow on beta) and | _underscore/Model/Rate/Entitlement.php, _underscore/Model/Client/Entitlement.php, _underscore/Model/Client/Address.php, dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql, dbchanges2/Core/2026-07-22a - EntitlementServiceAddressIdField.sql, dbchanges2/Client/2026-07-23a - EntitlementServiceAddressIdFieldPermission.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 | > **⚠ DEPLOYING beta→production, NOT YET PROD-VERIFIED (as of 2026-07-23).** TRUE-79533 is > beta-verified (PM Paulina tested the WH purchase flow on beta) and | _underscore/Model/Rate/Entitlement.php, _underscore/Model/Client/Entitlement.php, _underscore/Model/Client/Address.php, dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql, dbchanges2/Core/2026-07-22a - EntitlementServiceAddressIdField.sql, dbchanges2/Client_Rate/2026-07-23a - EntitlementServiceAddressIdFieldPermission.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/whole-home-warranty-purchase-guard.md

@@ -14,7 +14,7 @@ files:
   - _underscore/Model/Client/Address.php
   - dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql
   - dbchanges2/Core/2026-07-22a - EntitlementServiceAddressIdField.sql
-  - dbchanges2/Client/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql
+  - dbchanges2/Client_Rate/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql
   - test/@Mark/Rate/verify_wholehome_per_address_guard.php
 related:
   - clients/rate/profile.md
@@ -32,11 +32,12 @@ related:
 > **shared-interceptor merge hazard** gotcha and the **dangling-pin** / **unguarded prod
 > interceptor** gotchas before merging to `_production`.
 >
-> **🚨 LAUNCH BLOCKER (added 2026-07-23, tcox) — the standard `serviceAddressId` field has NO
-> READ ACL grant.** The custom→standard redesign shipped the column + `Core.RecordFields` row
-> but **not** the `AclFieldPermissions` read grant, so `GET /v2/entitlements?fields=serviceAddressId`
-> returns **403 `EZ-2`** for roles 1/2/4. Prod does **not** launch clean without the new
-> `Client/2026-07-23a` field-permission migration below — see
+> **🚨 LAUNCH BLOCKER — RESOLVED (migration built 2026-07-23, mhammontree; found 2026-07-23,
+> tcox) — the standard `serviceAddressId` field had NO READ ACL grant.** The custom→standard
+> redesign shipped the column + `Core.RecordFields` row but **not** the `AclFieldPermissions`
+> read grant, so `GET /v2/entitlements?fields=serviceAddressId` returned **403 `EZ-2`**. The fix
+> now ships as **`dbchanges2/Client_Rate/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql`**
+> (committed `b74f42a` on TRUE-79533) — see
 > **[Launch blocker: standard field needs a READ ACL grant](#launch-blocker-true-79533--the-standard-field-needs-a-read-acl-grant)**.
 
 ## Summary
@@ -144,7 +145,7 @@ during backend review (Jeff). This is the single biggest change since the beta b
 
 **The custom→standard redesign shipped the column and the `Core.RecordFields` row but NOT the
 `AclFieldPermissions` READ grant.** Probe-verified on **beta 2026-07-23**:
-`GET /v2/entitlements?fields=serviceAddressId` returns **403 `EZ-2`** for roles 1, 2, and 4
+`GET /v2/entitlements?fields=serviceAddressId` returns **403 `EZ-2`** (no read ACL row)
 (Entitlements has `Core.Records.aclDatabase = 'CLIENT'`, so the grant lives in each client DB).
 Without the grant, **production launches with the exact `EZ-2` failure beta hit** — the field is
 registered but unreadable, so the service cards cannot fetch the pin.
@@ -157,16 +158,20 @@ field is authorized through **`AclFieldPermissions`**, keyed by the **`Core.Reco
 because the `CustomRecordFields` row for `c_serviceAddressId` was deleted in the standard-field
 redesign. The read grant now has to be an **`AclFieldPermissions`** row instead.
 
-**Needed migration (proposed, on the TRUE-79533 branch):**
-`dbchanges2/Client/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql`, following the
-existing `Client/2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission.sql` precedent:
-- Resolve field ids via `Core.RecordFields` / `Core.Records` subselects (route `'entitlements'`,
-  fields `'serviceAddressId'` **and** its sibling `'number'`) — never hardcode ids.
-- **Mirror the sibling `number` field's per-role grants**, but force **`isWritable = 0`**:
-  `serviceAddressId` is written **server-side** by the guard's `postPost`, never by the API caller,
-  so it must be read-only.
-- Guard each INSERT with `NOT EXISTS` (verified against the Client blank DDL:
-  `AclFieldPermissions` is `UNIQUE (recordFieldId, roleId)`).
+**The migration that ships (built + committed `b74f42a` on TRUE-79533):**
+`dbchanges2/Client_Rate/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql`:
+- Resolves field ids via cross-schema `Core.RecordFields` / `Core.Records` subselects (route
+  `'entitlements'`, field `'serviceAddressId'`) — never hardcodes ids.
+- **Grants READ only (`isWritable = 0`)** — `serviceAddressId` is written **server-side** by
+  `_Model_Rate_Entitlement::postPost` via raw SQL, never by the API caller.
+- **Mirrors the reader ROLE(s) of the sibling standard FK `saleItemId` — which is `role 1` in
+  `Client_Rate`** (the same role the earlier `c_serviceAddressId` custom grant used). Although
+  the cross-role probe showed roles 1/2/4 all lacked a grant, **role 1 is the only actual reader**
+  of this field (Rate's toga2-view service cards), so the grant is role-1 only.
+- Guards each INSERT with `NOT EXISTS` — safe no-op until the field is registered
+  (`AclFieldPermissions` is `UNIQUE (recordFieldId, roleId)`).
+- **Scoped to `Client_Rate`, not a `Client/` fan-out** — Rate is the only client whose UI reads
+  the field today. A `Client/` fan-out grant is the follow-up if another client's UI needs it.
 
 ## Beta data migration — old-column pins are orphaned by the redesign (beta only, NO prod impact)
 
@@ -289,6 +294,17 @@ live carrier waterfall is opt-in via `RUN_LIVE=1` (defaults off). Verified **18/
   the deleted `2026-07-07a` interceptor registration was redundant — and why keeping it would have
   been a latent hazard: a fresh environment running both would **double-register**, firing
   `prePost` twice. **Recommend adding a `NOT EXISTS` guard to the `2026-07-15` file.**
+- **`AclFieldPermissions` has NO `isReadable` column — a ROW grants READ; `isWritable`
+  *additionally* grants WRITE** (reusable platform fact, verified against the api2 enforcement
+  code, not just schema). In `api2/Component/Api/V2/V2.php`, `getAclFieldPermissions()` (~line
+  5731) sets the field key regardless of `isWritable`, and the read-authorization checks test key
+  **presence** (`isset`/`array_key_exists`). Consequences: to make a field API-**readable** you
+  insert an `AclFieldPermissions` row (`isWritable = 0` for read-only); to make it **writable** set
+  `isWritable = 1`. And promoting a custom (`c_`) field to a **standard** field means its read grant
+  must be **re-created** as a standard `AclFieldPermissions` row (keyed by the `Core.RecordFields`
+  id) — the old `AclCustomFieldPermissions` grant (keyed by `CustomRecordFields` id) does **not**
+  carry over. This is exactly why the `c_serviceAddressId` grant did not cover the standard field
+  and the launch-blocker migration above was needed.
 - **`Core.RecordFields` has no `foreignRecordId` column** — FK resolution for `serviceAddressId`
   is entirely **model-side** (the `_Model_Client_Entitlement` FK declaration). The RecordField row
   only carries type/identifier/childPolicy/precision, mirroring sibling FKs `saleItemId`/`vendorId`.
@@ -297,6 +313,17 @@ live carrier waterfall is opt-in via `RUN_LIVE=1` (defaults off). Verified **18/
 
 ## Change history
 
+- 2026-07-23 — **READ-ACL grant BUILT — launch blocker resolved** (TRUE-79533, committed `b74f42a`).
+  Added `dbchanges2/Client_Rate/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql`: a
+  READ-only (`isWritable = 0`) `AclFieldPermissions` grant for the standard `serviceAddressId`,
+  resolving field ids cross-schema (route `entitlements`), `NOT EXISTS`-guarded. Final scope
+  corrected vs. the earlier proposal: **`Client_Rate` (not a `Client/` fan-out), role 1 only** —
+  mirroring the sibling standard FK `saleItemId`'s reader role (role 1 is the sole actual reader,
+  the toga2-view service cards). Recorded the reusable platform fact that **`AclFieldPermissions`
+  has no `isReadable` column — row presence grants READ, `isWritable` additionally grants WRITE**
+  (verified in `api2/Component/Api/V2/V2.php` `getAclFieldPermissions()` ~line 5731), which is why
+  a custom→standard promotion must re-create the read grant as an `AclFieldPermissions` row.
+  (mhammontree)
 - 2026-07-23 — **LAUNCH BLOCKER found: the standard `serviceAddressId` field has NO read ACL grant**
   (tcox). Probe-verified on beta: `GET /v2/entitlements?fields=serviceAddressId` → 403 `EZ-2` for
   roles 1/2/4 (`aclDatabase=CLIENT`). Standard fields are authorized via **`AclFieldPermissions`**

package/package.json

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