toga-ai 1.0.442 → 1.0.443

package/knowledge/sessions/2026-07-27-true-79533-pin-depth-mhammontree.md

@@ -1,7 +1,7 @@
 ---
 type: session
 slug: true-79533-pin-depth
-title: TRUE-79533 WH service-address pin blocked by depth=-1 starving postPost
+title: TRUE-79533 WH service-address pin — SHIPPED & verified on beta (was blocked by depth=-1)
 author: mhammontree
 repos: [_underscore, dbchanges2, toga2-view]
 framework: "2.0"
@@ -14,60 +14,61 @@ updated: 2026-07-27
 # Session: true-79533-pin-depth
 **Date:** 2026-07-27
 **Project/Repo:** _underscore / dbchanges2 / toga2-view (2.0, client Rate)
-**Task:** Get the validated Whole Home Warranty service address to pin (`Entitlements.serviceAddressId`) and render on beta. Backend is done and correct; the blocker was the beta purchase POST sending `depth=-1`, which starved the `postPost` interceptor of the just-created address id. **FIX CHOSEN: front-end drops `depth`; deploying to beta now — awaiting verification.**
+**Task:** Pin the validated Whole Home Warranty service address (`Entitlements.serviceAddressId`) and render it on beta. **DONE + verified on beta 2026-07-27.** The blocker was the purchase POST sending `depth=-1`, which starved the `postPost` interceptor of the created address id; the front-end dropped `depth` and it now works. Remaining = deploy/merge close-out + knowledge captured.
 
 ---
 
 ## What WORKED
 <!-- Include specific file paths and evidence -->
-- **Backend pin implemented** in `_underscore/Model/Rate/Entitlement.php` `postPost` → `persistWarrantyServiceAddress`: reads the created address id from the in-memory hydrated payload (`$payload->contact->primaryContactAddress->address->id`), then `UPDATE Addresses SET isValidated=1` + `UPDATE Entitlements SET serviceAddressId=… WHERE uuid=…`. Committed `dff1fb5e`. **Proven working AND already on the beta backend**: ET100057 — a purchase whose request had **no `depth` param** (query string `transactionId=…`, 64,650-byte deep response) — pinned `serviceAddressId=56`, address 56 (STE 400) `isValidated=1`, on the same beta instance that fails for `depth=-1` calls. This is the exact config the FE fix reproduces.
-- **`serviceAddressId` is a STANDARD field** on base `_underscore/Model/Client/Entitlement.php:20` (`FIELD_FOREIGNKEY` → `_Model_Client_Address`), inherited by the Rate model.
-- **Display EZ-2 fixed**: `dbchanges2/Client_Rate/2026-07-24a - AddressIdFieldPermission.sql` grants READ on `Addresses.id` for roles 1/2/3. Committed `ea1e0fb`. Applied on beta manually and verified.
-- **Hard-blocks return HTTP 400** via `_Exception_Validation` (committed `41a5dc1a`) — mapped by `api2/Controller/Index.php:204-222`. (NOT yet on beta — see blockers.)
-- **Dedup** `hasActiveWarrantyAtAddress` forces WRITE host + disables query cache; `COALESCE(serviceAddressId, ContactAddresses.addressId)` fallback.
-- **Root cause proven via `Logs_Rate.Api`** (MCP env `dev-sandbox`): local-FE and beta-FE purchases hit the SAME beta instance (`i-0ce5624547cfecc93`). Only difference = request query string depth: no-depth → 64 KB deep → **pins**; `depth=-1` → 644 B shallow (`meta.calcDepth: 1`, no `address` node) → **starved**.
-- **`-1` source = front-end**: `toga2-view/src/pages/CheckOut/api/checkoutApi.ts:21` (`createService` passed `{ 'depth': -1 }`). Confirmed in the logged query string.
-- **Interceptor config (Rohan-confirmed):** `ApiPayloadInterceptors` `minDepth` defaults to **3** when null; entitlements `postPost` (id 2) is explicitly **5**; `prePost` (id 4) & sales-orders (id 3) are null→3. Omitting the request `depth` yields a full/deep build that clears the 5 floor and includes the `address` node.
+- **END-TO-END VERIFIED ON BETA (2026-07-27):** after Tanner removed `depth` from the FE purchase call, both post-fix purchases pinned on their own, no backfill — ET100068 (`serviceAddressId=67` → 233 S WACKER DR, `isValidated=1`) and ET100067 (`serviceAddressId=66` → 1864 HIGH GROVE LN STE 1900, `isValidated=1`). Everything before the FE deploy is still null (clean cutoff). Paulina is PM-testing beta.
+- **FE fix = drop the `depth` param** at `toga2-view/src/pages/CheckOut/api/checkoutApi.ts` (`createService` no longer sends `{depth:-1}`). Deployed to beta. This reproduces the proven-good no-depth config (ET100057 had pinned the same way pre-fix).
+- **Backend pin** in `_underscore/Model/Rate/Entitlement.php` `postPost`→`persistWarrantyServiceAddress`: reads the created address id from the in-memory hydrated payload (`$payload->contact->primaryContactAddress->address->id`), sets `Addresses.isValidated=1` + `Entitlements.serviceAddressId`. Committed `dff1fb5e`. Already live on beta (that's why ET100057/67/68 pinned).
+- **`serviceAddressId` = STANDARD FK field** on base `_underscore/Model/Client/Entitlement.php:20`.
+- **Display EZ-2 fixed**: `dbchanges2/Client_Rate/2026-07-24a - AddressIdFieldPermission.sql` grants read on `Addresses.id` (roles 1/2/3). Committed `ea1e0fb`; applied+verified on beta.
+- **Hard-blocks → HTTP 400** via `_Exception_Validation` (committed `41a5dc1a`), mapped by `api2/Controller/Index.php:204-222`. (On `TRUE-79533`, NOT yet on beta — see blockers.)
+- **Root cause proven via `Logs_Rate.Api`**: local-FE and beta-FE calls hit the SAME beta instance (`i-0ce5624547cfecc93`); only the request `depth` differed (no-depth → 64 KB deep → pins; `depth=-1` → 644 B shallow, `calcDepth 1`, no `address` node → starved). The `-1` came from the FE (`checkoutApi.ts`), not the interceptor.
+- **Interceptor config (Rohan-confirmed):** `ApiPayloadInterceptors.minDepth` defaults to 3 (null); entitlements `postPost` = 5; `prePost`/sales-orders = null→3.
+- **Knowledge CAPTURED + PUSHED (2026-07-27):** 9 docs — Rate WH guard (draft→active), service-card Addresses.id ACL, aig-contract standard-field correction, api2 EZ-2 (`id` case), and 5 elevated standards/architecture (depth-starvation + `_Exception_Validation` in `2.0/standards/backend-php.md`; uncommitted-nested-write in `_underscore/architecture.md`; `_sandbox-dev` branch map + `Logs.Api` in the api2 deploy workflow; committed-PAT security note in `api2/architecture.md`).
 
 ## What did NOT work — DO NOT RETRY THESE
 <!-- Exact failure reasons — do not vague-ify -->
-- **Forcing the write host inside `persistWarrantyServiceAddress`** (commit `7b63955d`, removed in `dff1fb5e`): NO EFFECT. V2 already disables the read host for the whole create block (`V2.php:5024`) — the lookup was already on the writer.
-- **The 3-table JOIN lookup** (`Entitlement → Contacts.primaryContactAddressId → ContactAddresses → addressId`) in postPost: returns 0 rows *in-request* even on the writer; resolves only *post-commit*. Superseded by the payload approach.
-- **Payload-based `$address->id` on beta with `depth=-1`**: null — the shallow payload (`calcDepth 1`) has NO `contact.primaryContactAddress.address` node at all, so there's nothing to read. Code is correct; depth is the cause.
-- **Merging `_underscore` to `_beta` did NOT deploy to beta.** API-Sandbox-Dev EB pulls `_underscore` from **`_sandbox-dev`** via `api2/.platform/hooks/prebuild/git.sh` + `.ebextensions/git.sandbox-dev.json`.
-- **"Removed depth" curl test (earlier)**: the edited curl STILL had `depth=-1` (per logged `queryString`) — proved nothing.
-- **Single-host vs multi-host connection theory**: DISPROVEN — same beta instance both ways; the variable is the request `depth`, not topology.
+- **Forcing the write host inside `persistWarrantyServiceAddress`** (commit `7b63955d`, removed in `dff1fb5e`): NO EFFECT — V2 already disables the read host for the whole create block (`V2.php:5024`).
+- **The 3-table JOIN lookup** (`Entitlement → Contacts.primaryContactAddressId → ContactAddresses → addressId`) in postPost: returns 0 rows *in-request* even on the writer (resolves only post-commit). Superseded by the payload approach.
+- **Payload-based `$address->id` while the FE sent `depth=-1`**: null — the shallow payload (`calcDepth 1`) has NO `contact.primaryContactAddress.address` node. Code was correct; depth was the cause.
+- **Merging `_underscore` to `_beta`**: does NOT deploy to beta — API-Sandbox-Dev pulls `_underscore` from **`_sandbox-dev`** via `api2/.platform/hooks/prebuild/git.sh` + `.ebextensions/git.sandbox-dev.json`.
+- **"Removed depth" curl test (earlier)**: the edited curl STILL had `depth=-1` in the logged query string — proved nothing.
+- **Single-host vs multi-host connection theory**: DISPROVEN — same beta instance both ways; the variable was request `depth`.
+- **Relying on `minDepth` to protect the interceptor**: it's set to 5 on the postPost row yet the payload still built at `calcDepth 1` for a `depth=-1` request — the clamp is a latent no-op (framework bug to ticket). The real fix was the FE dropping `depth`.
 
 ## Not tried yet (candidates for next session)
-- **PRIMARY (in flight):** Tanner removed `depth` from `checkoutApi.ts:21` on the front-end; the `toga2-view` change is **deploying to beta now**. Verify a fresh beta purchase pins (see Exact next step). This reproduces the proven-good ET100057 config.
-- **FALLBACK if the FE fix somehow doesn't take:** on beta `Client_Rate`, `UPDATE ApiPayloadInterceptors SET minDepth = 10 WHERE id = 2;`, fire a purchase, check whether `calcDepth` rises and it pins. (Open Q: does the `minDepth` clamp engage for the `-1` sentinel? It's 5 yet built at `calcDepth 1`.)
-- Merge `_underscore` `TRUE-79533` → `_sandbox-dev` + deploy (ships the `_Exception_Validation` 400 fix + full backend; pin itself is already on beta).
-- Merge `dbchanges2` `TRUE-79533` for prod parity (beta already has the migrations).
-- Run `/capture`.
-- File side tickets: (1) framework `minDepth`-clamp no-op for low/`-1` depth (starves ALL payload interceptors); (2) AIG contract block has the SAME `depth` starvation — silently skipped for beta-FE purchases; (3) SECURITY: plaintext GitHub PAT committed in `api2/.ebextensions/git.*.json` — rotate + move to env config.
+- **Merge `_underscore` `TRUE-79533` → `_sandbox-dev` + deploy** — puts the `_Exception_Validation` 400-fix (`41a5dc1a`) on beta so Paulina's *blocked-purchase* testing (duplicate / unverifiable address) shows a clean 400 toaster instead of a 500 + stack trace. Do this before she hits those paths.
+- **Merge `dbchanges2` `TRUE-79533`** to its deploy branch for prod parity (beta already has the migrations applied).
+- **File the framework ticket:** `ApiPayloadInterceptors.minDepth` clamp does not deepen the built payload for a `depth=-1` request (WO-1 says "raised to 5" but `calcDepth` stays 1) — starves ANY payload interceptor. Plus: AIG contract block had the same starvation; and the committed GitHub PAT in `api2/.ebextensions/git.*.json` needs rotating + moving to SSM.
+- Optionally credit Tanner as an `owners` on the FE-touching Rate doc once his kb-username is known.
 
 ## Current file state
 | File | Status | Notes |
 |------|--------|-------|
-| `_underscore/Model/Rate/Entitlement.php` | Committed on `TRUE-79533` (HEAD `41a5dc1a`) | payload pin (`dff1fb5e`) + dedup write-host + `_Exception_Validation` (`41a5dc1a`). Pin already on beta; the 400-fix is NOT (needs `_sandbox-dev` merge). |
+| `toga2-view/src/pages/CheckOut/api/checkoutApi.ts` | **FIXED + deployed to beta (Tanner)** | dropped `{depth:-1}` → deep payload reaches `postPost`. THE unblocker; pin now works. |
+| `_underscore/Model/Rate/Entitlement.php` | Committed on `TRUE-79533` (HEAD `41a5dc1a`) | payload pin (`dff1fb5e`, already on beta) + dedup write-host + `_Exception_Validation` (`41a5dc1a`, NOT yet on beta). |
 | `_underscore/Model/Client/Entitlement.php` | Committed | `serviceAddressId` standard FK (line 20). |
-| `dbchanges2/Client_Rate/2026-07-24a - AddressIdFieldPermission.sql` | Committed (`ea1e0fb`) | `Addresses.id` read ACL. Applied on beta. |
-| `dbchanges2` serviceAddressId col + `Core` field + ACL migrations | Committed on `TRUE-79533` | Applied on beta manually; branch needs merge for prod. |
-| `toga2-view/src/pages/CheckOut/api/checkoutApi.ts` | **Tanner removed `depth` — DEPLOYING to beta now** | Line 21 `{ 'depth': -1 }` dropped so `postPost` gets a deep payload. THE unblocker. |
-| `test/@Mark/Rate/verify_wholehome_per_address_guard.php` | Updated (personal, not in a repo) | `c_serviceAddressId` → `serviceAddressId`; documents the depth caveat. |
+| `dbchanges2/Client_Rate/2026-07-24a - AddressIdFieldPermission.sql` | Committed (`ea1e0fb`) | Applied on beta. Needs branch merge for prod. |
+| `dbchanges2` serviceAddressId col + `Core` field + ACL | Committed on `TRUE-79533` | Applied on beta manually; needs merge for prod. |
+| team KB (`~/toga-tech/knowledge/…`) | **9 docs published to `_main` (capture)** | Rate WH guard active + 5 elevated standards/arch docs. |
+| `test/@Mark/Rate/verify_wholehome_per_address_guard.php` | Updated (personal, not in a repo) | Not team knowledge. |
 
 ## Decisions made
-- **Fix depth on the FRONT-END (drop the `depth` param)** rather than bumping the interceptor `minDepth`. Rationale: it reproduces the already-proven ET100057 (no-depth) config that pinned on beta, needs no DB config change, and un-starves the AIG block for free. The `minDepth` bump remains the fallback / the proper systemic guardrail. (Rohan confirmed minDepth 3-default / 5 on postPost.)
-- **Pin from the in-memory hydrated payload, not a DB read-back** (in-request reads can't see uncommitted nested writes; `getFullModelData` hydrates the payload before `postPost`).
+- **Fix depth on the FRONT-END (drop the `depth` param)** rather than bumping the interceptor `minDepth`. Rationale: reproduces the proven ET100057 no-depth config, no DB config change, and un-starves the AIG block too. Verified working on beta. `minDepth` bump remains the fallback / the systemic guardrail (whose clamp bug is now a separate ticket).
+- **Pin from the in-memory hydrated payload, not a DB read-back** (in-request reads can't see the txn's own uncommitted nested writes).
 - **`serviceAddressId` = STANDARD field** (per Jeff), not `c_serviceAddressId`.
-- **Hard-blocks throw `_Exception_Validation`** → HTTP 400 + surfaced message (FE checkout expects 400).
+- **Hard-blocks throw `_Exception_Validation`** → HTTP 400 + message (FE expects 400).
 
 ## Blockers
-- **Verification pending** — the front-end `depth` removal is mid-deploy to beta; can't confirm the pin until it lands and a fresh purchase is made.
-- The `_Exception_Validation` 400-fix (`41a5dc1a`) and the rest of `TRUE-79533` are on `TRUE-79533` but NOT yet on beta (beta deploys `_underscore` from `_sandbox-dev`). Does NOT block the pin test (the pin code is already on beta), but needs merging for the 400/toaster behavior + prod.
+- **None blocking the pin** — it's verified working on beta.
+- Soft/pending: the `_Exception_Validation` 400-fix (`41a5dc1a`) is not yet on beta (beta deploys `_underscore` from `_sandbox-dev`), so Paulina's blocked-purchase paths currently return 500 until the `_sandbox-dev` merge+deploy. Not a pin blocker.
 
 ## Exact next step
-> As soon as Tanner's `toga2-view` deploy lands, make ONE fresh WH purchase on beta and verify in the DB (MCP `dev-sandbox`, `Client_Rate`): the newest WH entitlement has `serviceAddressId` populated AND its `Addresses.isValidated = 1`, with NO manual backfill. Also confirm the create response no longer shows the `WO-1` depth warning (and `meta.calcDepth` is higher), and that AIG outbound calls resume in `Logs_Rate.Api`. If it pins → success; then merge `_underscore TRUE-79533` → `_sandbox-dev` (for the 400 fix), merge `dbchanges2`, and run `/capture`. If it still returns null → apply the FALLBACK (`UPDATE ApiPayloadInterceptors SET minDepth=10 WHERE id=2` on beta) and re-test.
+> Merge `_underscore` `TRUE-79533` → `_sandbox-dev` and deploy API-Sandbox-Dev (prebuild hook re-clones `_sandbox-dev`), so the `_Exception_Validation` hard-block 400s reach beta before Paulina tests duplicate/invalid-address rejections. Then merge `dbchanges2` `TRUE-79533` for prod parity, and file the framework `minDepth`-clamp-no-op ticket (+ AIG-starvation + committed-PAT follow-ups). Verify a deliberate duplicate-address purchase on beta returns HTTP 400 with the toaster message (not 500).
 
 ---
 _Saved by /session-save on 2026-07-27_

package/package.json

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