toga-ai 1.0.427 → 1.0.428

package/knowledge/2.0/apps/_underscore/features/acl-permission-chain.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-21
+updated: 2026-07-23
 owners: ["jcardinal", "mhammontree", "tcox"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -56,6 +56,13 @@ writable). Without it the field is rejected on write **and** is unreadable:
 - **`AclFieldPermissions` is `UNIQUE (recordFieldId, roleId)`** (Client blank DDL) — guard inserts
   with `NOT EXISTS`. For a **read-only, server-written** field (one populated by a `postPost`
   interceptor rather than the API caller), grant `isWritable = 0`.
+- **A read-only field only needs a grant on the role(s) that actually READ it — find that role by
+  mirroring a sibling field of the same kind the readers already consume**, rather than blanket-granting
+  every role. E.g. the standard FK `serviceAddressId` mirrored its sibling FK `saleItemId`, whose sole
+  reader in `Client_Rate` is **role 1** (the toga2-view service cards) — so a single role-1 read grant
+  sufficed, NOT a 1/2/4 fan-out (a cross-role probe had shown roles 1/2/4 all lacked the grant, but only
+  role 1 actually reads the field). Grant `isWritable = 0` for a server-written field; resolve the role
+  by name/subselect (ids differ per client DB). Beta-proven on Rate `Client_Rate` 2026-07-23.
 
 ### Standard field vs. custom (`c_`) field — TWO different permission tables
 
@@ -199,6 +206,11 @@ the field.
 
 ## Change history
 
+- **2026-07-23** — TRUE-79533: noted that a **read-only field only needs a grant on the role(s) that
+  actually read it** — mirror a sibling field of the same kind the readers already consume rather than
+  granting every role. The standard FK `serviceAddressId` mirrored `saleItemId`'s reader, **role 1** in
+  `Client_Rate` (the toga2-view service cards), so a single role-1 read grant sufficed (not a 1/2/4
+  fan-out). (tcox)
 - **2026-07-23** — TRUE-79533: documented the **READ side** of `AclFieldPermissions` — a registered
   field with no grant returns **`EZ-2`** on read (the counterpart of the write code `EV-9`), and
   the **standard vs. custom** split: standard fields use `AclFieldPermissions` (keyed by

package/knowledge/2.0/apps/toga2-view/features/query-string-builder.md

@@ -60,5 +60,3 @@ easy to misread as an API problem.
   values to `String` before `urlEncode` — a numeric value (first hit via `fetchAddressesByIds`)
   threw `input.replace is not a function` and silently aborted the request client-side. Added
   regression tests. (tcox)
-</content>
-</invoke>

package/knowledge/2.0/apps/toga2-view/features/zip-validation-contact-phone.md

@@ -46,4 +46,3 @@ the store when it changed.
   field (a different covered property can have a different contact number). Previously the field
   was disabled once the store held a phone, and the post-purchase save made the first purchase lock
   it for every later visit. `save-if-different` retained. (tcox)
-</content>

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

@@ -6,8 +6,8 @@ project: _Underscore
 client: rate
 type: client-feature
 status: active
-updated: 2026-06-29
-owners: [mhammontree]
+updated: 2026-07-23
+owners: [mhammontree, tcox]
 files:
   - _underscore/Model/Rate/Entitlement.php
   - _underscore/ApiRequest.php
@@ -96,9 +96,21 @@ creation vs. cancellation. This is an accepted, documented limitation — not an
   address, so an entitlement with no address never even attempts contract creation (and
   never logs a `/contract` call).
 - **Auth-induced failures are blind to the monitor** — see the detection limitation above.
+- **The AIG-success branch REASSIGNS `$payload->uuid`** (`$payload->uuid = _String::generateUuid()`,
+  repurposed as the AIG contract number) — and it does so **in the same `postPost`** that pins the WH
+  service address. On the pre-redesign build the pin step ran **after** this reassignment and keyed
+  off `$payload->uuid`, so **every successful AIG contract silently broke the WH address pin** (the
+  pin lookup matched no row). Preserve the ordering fix — snapshot the entitlement uuid **before**
+  this branch. See the
+  [WH per-address purchase guard](whole-home-warranty-purchase-guard.md) "AIG-success clobbers the
+  pin" gotcha (`_underscore` `_beta` `9c2e4b1c`).
 
 ## Change history
 
+- 2026-07-23 — Documented that the **AIG-success branch reassigns `$payload->uuid`** (as the contract
+  number) inside the shared `postPost`, which silently broke the WH service-address pin on the
+  pre-redesign build (pin keyed off the now-reassigned uuid). Fixed by snapshotting the entitlement
+  uuid before the AIG branch (`_underscore` `_beta` `9c2e4b1c`). Cross-linked the WH guard doc. (tcox)
 - 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

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

@@ -106,6 +106,10 @@ Ticket: TRUE-79533. Business rule owner: PM Paulina.
    `Addresses.isValidated = 1` and writes `Entitlements.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`).
+   **The entitlement UUID is snapshotted up front** (`$entitlementUuid = $payload->uuid`) at the
+   top of `postPost`, **before** the AIG branch runs — because the AIG-success branch reassigns
+   `$payload->uuid` (see the "AIG-success clobbers the pin" gotcha). The pin lookup must use the
+   snapshot, not `$payload->uuid`.
 6. All SQL uses `_Database::escape()` / int-casts — `_Query` has **no bind API** in this path.
 
 ## Field & model: `serviceAddressId` is now a STANDARD field (reviewer Jeff)
@@ -280,6 +284,22 @@ live carrier waterfall is opt-in via `RUN_LIVE=1` (defaults off). Verified **18/
 - **`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).
+- **ROOT CAUSE of NULL pins on the pre-redesign build: the pin silently fails whenever the AIG
+  contract is created SUCCESSFULLY.** The old `postPost` pinned the entitlement by `$payload->uuid`,
+  but the **AIG-success branch reassigns `$payload->uuid = _String::generateUuid()`** (reusing it as
+  the AIG contract number) **before** the pin step. So on an AIG success the pin lookup by
+  `$payload->uuid` matches **no row**, logs `"TRUE-79533: could not resolve service address"`, and
+  gives up — leaving `Entitlements.serviceAddressId` (and, pre-redesign, `c_serviceAddressId`) NULL
+  and the purchase's `Addresses.isValidated` NULL (that pair is the fingerprint of a lost pin).
+  Pinning is therefore **intermittent — it works only when AIG auth FAILS** (the branch that
+  clobbers the uuid never runs). Proven on beta `Client_Rate` 2026-07-23: entitlement 68 pinned,
+  69/70/71 unpinned despite an intact Contact→`primaryContactAddressId`→ContactAddresses chain.
+  **Fixed in `_underscore` `_beta` commit `9c2e4b1c`**: `postPost` snapshots
+  `$entitlementUuid = $payload->uuid` up front, before the AIG branch, and pins by the snapshot.
+  **DEPLOY DEPENDENCY:** any environment still running a **pre-redesign** `api2`/`_underscore` build
+  loses the address pin every time AIG succeeds; the fix only takes effect on **EB redeploy**
+  (api2 pulls `_underscore` at deploy). This is the mechanism behind the COALESCE fallback and the
+  dangling-pin gotcha below — the fallback is what keeps the dedup correct while pins are missing.
 - **Dedup is defeated by a DANGLING pin (not just a NULL one).** The COALESCE fallback covers a
   **NULL** `serviceAddressId`, but if `serviceAddressId` points at a **deleted `Addresses` row**,
   the join drops that entitlement and it becomes **invisible to the guard** — a duplicate WH slips
@@ -324,6 +344,17 @@ live carrier waterfall is opt-in via `RUN_LIVE=1` (defaults off). Verified **18/
   (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 — **Root cause of intermittent NULL pins + guard hardening confirmed** (tcox). (1) The
+  `postPost` service-address pin **silently fails whenever the AIG contract creation SUCCEEDS**,
+  because the AIG-success branch reassigns `$payload->uuid` before the pin step, so pinning by
+  `$payload->uuid` matches no row (fingerprint: `serviceAddressId` + `Addresses.isValidated` both
+  NULL). Proven on beta (entitlement 68 pinned, 69/70/71 not). Fixed in `_underscore` `_beta`
+  `9c2e4b1c` (snapshot `$entitlementUuid` up front). Deploy-dependency: pins are lost on AIG success
+  on any pre-redesign build until EB redeploy. (2) The dedup blind spot (unpinned entitlements
+  invisible to `hasActiveWarrantyAtAddress` — demonstrated live: two active WH at "STE 250" slipped
+  through on the old build) is **CLOSED in `_beta` `a9f408bc`** — the dedup joins Addresses via
+  `COALESCE(serviceAddressId, ContactAddresses.addressId)`, disables the query cache for the read,
+  and documents an accepted TOCTOU. (tcox)
 - 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/knowledge/clients/rate/profile.md

@@ -3,6 +3,7 @@ title: "Rate"
 framework: "2.0"
 apps:
   - _underscore
+  - api2
   - saml
   - toga2-view
   - worker
@@ -12,8 +13,8 @@ project: SAML SSO Gateway
 client: rate
 type: profile
 status: active
-updated: 2026-06-30
-owners: ["rgirish", "bala", "mhammontree"]
+updated: 2026-07-23
+owners: ["rgirish", "bala", "mhammontree", "tcox"]
 files: []
 related:
   - clients/rate/features/saml-sso.md

package/package.json

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