toga-ai 1.0.419 → 1.0.421

package/knowledge/2.0/apps/ai-bdr/features/web-funnel-app.md

@@ -6,7 +6,7 @@ project: AI-BDR
 client: shared
 type: feature
 status: active
-updated: 2026-07-21
+updated: 2026-07-23
 owners: [tcox]
 files:
   - bdr/PLAN.md
@@ -374,24 +374,33 @@ PRODUCTION credential set (`TOGA_API_BASE_URL = https://api.togahub.com/v2`).
 - **Restart the dev server after creating `.env.local`** — Next reads env files only at
   server startup. `.env.*` is gitignored in BDR.
 
-## Deploy status (AWS Amplify — app EXISTS, first build shipping)
+## Deploy status (AWS Amplify — LIVE + verified 2026-07-23)
 
-**The Amplify app now exists (2026-07-21):** branch `_dev-sandbox` deploys to
-**`dev-sandbox.d65bvvjrww97g.amplifyapp.com`** (supersedes the prior "no Amplify app yet"
-status). Go-live tracking: ClickUp **868kdf4tj "BDR - create amplify and sandbox route"**
+**The BDR site is LIVE and verified (2026-07-23):** branch `_dev-sandbox` (Amplify default
+domain `d65bvvjrww97g.amplifyapp.com`) serves the funnel at the custom domain
+**https://bdr.dev.sandbox.togatech.com/** — the landing page returns `200` and
+`GET /api/contact?hsContactId=131770626674` returns `200` with the contact JSON (server env is
+now present at runtime). This supersedes the 2026-07-21 "first build shipping / awaiting console
+vars" status. Go-live tracking: ClickUp **868kdf4tj "BDR - create amplify and sandbox route"**
 (urgent, Sprint 82). (ClickUp showed Alex Peterson as assignee; the team said Jeff picked it
 up — confirm the real owner before assuming.)
 
 - **CRITICAL — the build-spec must WRITE the console env vars into `.env.production` at build
-  time (Amplify Next-SSR recipe).** The first deployment surfaced a build-spec bug: the old
-  `amplify.yml` only had branch cases for `_production` / `_beta`, each doing
-  `cp .env.production .env.local` — which expects a **committed** `.env` file that (correctly)
-  does not exist (secrets are never committed). **No branch case matched `_dev-sandbox` at all**,
-  so every deploy shipped with **ZERO server env vars**. Amplify console env vars exist only at
-  **build time**; the Next SSR **runtime** reads `.env.production` from the build artifact — so the
-  build must materialize them. Fix (commit `e17d804`): during build,
-  `env | grep -E '^(HUBSPOT_|TOGA_|NEXT_PUBLIC_|RATE_LIMIT_)' >> .env.production`. The same broken
-  `cp` pattern would have bitten the `_production` launch too.
+  time (Amplify Next-SSR recipe). RESOLVED + verified live 2026-07-23.** Root cause, now confirmed
+  with git evidence: the old `amplify.yml` was inherited from the old `info` repo (authored by
+  Rohan) and did `cp .env.production .env.local` per branch, with cases only for
+  `_production` / `_beta`. That worked in `info` **only because the info repo COMMITS its real
+  `.env` files to git** (`git ls-files` shows `.env.beta`, `.env.local`, `.env.production` tracked,
+  containing real credentials — see the security gotcha below). The BDR repo correctly gitignores
+  all `.env` files (only `.env.example` is tracked, per team git rules), so the `cp` had nothing to
+  copy **and** no branch case matched `_dev-sandbox` — every deploy shipped with **ZERO server env
+  vars**. Amplify console env vars exist only at **build time**; the Next SSR **runtime** reads
+  `.env.production` from the build artifact — so the build must materialize them. Fix (commit
+  `e17d804` on `_dev-sandbox`, `amplify.yml` build phase, before `npm run build`):
+  `env | grep -E '^(HUBSPOT_|TOGA_|NEXT_PUBLIC_|RATE_LIMIT_)' >> .env.production || true` — the
+  AWS-documented pattern for Next SSR on Amplify. It is **branch-agnostic** (no per-branch case to
+  miss), and secrets stay in the Amplify console, never in git. The same broken `cp` pattern would
+  have bitten the `_production` launch too.
 - **Symptom chain when the env vars are missing (what "no vars" looks like end-to-end):**
   page-prime's HubSpot fetch throws → lead ref comes back empty → the **anonymous-visit guard
   notice shows even with a valid `?hsContactId`** → `GET /api/contact` returns
@@ -400,18 +409,35 @@ up — confirm the real owner before assuming.)
 - **OPERATIONAL — env vars saved AFTER a build starts do NOT reach that build.** They are baked in
   at build time, so after adding/changing console vars you must **"Redeploy this version"** for
   them to take effect — a fresh save alone does nothing for an in-flight or already-built deploy.
+  (This bit us 2026-07-23: the first post-fix build ran **before** the console vars existed and
+  still `500`'d, which looked like the fix had failed — it was just the pre-vars build.)
+- **OPERATIONAL — a buildspec saved in the console Build settings OVERRIDES the repo `amplify.yml`.**
+  If an `amplify.yml` change in the repo seems to have no effect, check **Console → Build settings**
+  for an inline buildspec shadowing it, and reconcile them before assuming the repo change is wrong.
+- **OPERATIONAL — adding a custom domain does NOT trigger a rebuild.** Wiring
+  `bdr.dev.sandbox.togatech.com` to the app does not by itself redeploy; if the running build
+  predates a needed env/spec change, run **"Redeploy this version"** separately.
 - **Amplify must be configured for SSR hosting (NOT static export)** — the app is server-rendered
   (server components, route handlers, and the `proxy.ts` edge proxy all require the SSR/compute
   runtime). Point the app at branch `_dev-sandbox`.
-- **7 env vars go in the Amplify console** (never the values — **values live in `info/.env.local`**,
-  the production credential set): the 5 server-side ones `HUBSPOT_ACCESS_TOKEN`,
-  `TOGA_API_BASE_URL`, `TOGA_CLIENT_ID`, `TOGA_CLIENT_API_UUID`, `TOGA_CLIENT_API_SECRET`, plus
-  `TOGA_WORKER_URL` (the fast-dial gate — unset ⇒ cron-only) and `NEXT_PUBLIC_GA_MEASUREMENT_ID`
-  (GA4). See the parity audit for the full 7-var accounting.
-- **Status at capture:** env fix pushed (`e17d804` on `_dev-sandbox`); awaiting the console vars +
-  a green build for the first successfully deployed page-prime. The primary-phone self-heal (commit
-  `4ac579e`, see the phone-less bug above) is already on `_dev-sandbox`, so the first good build
-  ships that fix too.
+- **7 env vars go in the Amplify console** (never the secret **values** — those **live in
+  `info/.env.local`**, the production credential set). Console recipe that completed the fix
+  (verified working 2026-07-23): **AWS Amplify console → BDR app → Hosting → Environment variables
+  → Manage variables**, applied to **all branches**. The 7: the 4 secrets `HUBSPOT_ACCESS_TOKEN`,
+  `TOGA_CLIENT_ID`, `TOGA_CLIENT_API_UUID`, `TOGA_CLIENT_API_SECRET` (values only in the console +
+  `info/.env.local`, never here); plus the non-secret config `TOGA_API_BASE_URL`
+  (`https://api.togahub.com/v2`), `TOGA_WORKER_URL` (`https://worker.togahub.com/` — new vs. info;
+  enables fast dial), and `NEXT_PUBLIC_GA_MEASUREMENT_ID` (`G-0BE4RFNLY0`, a public GA4 id).
+  `TOGA_PUBLIC_TOKEN_URL` and `NEXT_PUBLIC_ENV` are dead even in `info` and are intentionally NOT
+  carried over. See the parity audit for the full accounting.
+- **Status (2026-07-23): LIVE and verified.** After the console vars were saved and the version was
+  redeployed, the deployed page-prime works: `https://bdr.dev.sandbox.togatech.com/` returns `200`
+  and `GET /api/contact?hsContactId=131770626674` returns `200` with contact JSON. The primary-phone
+  self-heal (commit `4ac579e`) is live, and fast dial is now wired in the deployed env
+  (`TOGA_WORKER_URL` set). **Still pending (deferred to next session):** the deployed **Call Now**
+  smoke test — which is also **fast dial's first live run** end-to-end (local testing never
+  exercised `TOGA_WORKER_URL`, so the deployed Call Now is the first time the fast-dial POST fires
+  in a real deploy).
 - **Phase 8 WAF pairing.** `BDR/PLAN.md` Phase 8 specifies a **per-IP rate rule on the CloudFront
   distribution / WAF** that pairs with the in-app token-bucket limiter (the app limiter is
   defense-in-depth only; the edge WAF rule is the authoritative control — see the enumeration
@@ -514,6 +540,15 @@ up — confirm the real owner before assuming.)
   happen inside the route handler. See "Request-a-call is fully server-side" above. And note
   setting `dtNextContactRequested` does not guarantee a call — the worker2 dialer eligibility
   SQL decides (a phone-less contact is silently never dialed; see that section).
+- **HIGH (security) — the old `info` repo COMMITS real production credentials to git.** `info`'s
+  `.env.beta` / `.env.local` / `.env.production` are **tracked** files (confirmed via `git ls-files`)
+  containing the real **HubSpot access token** and **Toga API client secret**. Those credentials are
+  in git history and must be treated as **compromised → rotate**. The AI-BDR credential-rotation
+  ticket now covers the HubSpot token + Toga API secret **in addition to** the hardcoded Vapi bearer
+  at `worker2/Worker/Ai/Bdr/Vapi.php:6` (see
+  `../../worker2/features/vapi-webhook-handler.md`). BDR itself correctly gitignores all `.env` files
+  — this is an `info`-repo problem that BDR touches only because it sources its local-dev values from
+  `info/.env.local`. Never record credential **values** in the KB — location only.
 - **Standing rule: never add more PII fields to `ClientLeadRef`.** Phone is the one
   deliberate exception (visitor's own number, shown back to them, never logged). Every field
   on `ClientLeadRef` crosses to the public client and is exposed to the enumeration risk
@@ -554,6 +589,22 @@ up — confirm the real owner before assuming.)
   harness; pull it with `npx toga-ai`.
 
 ## Change history
+- 2026-07-23 — **BDR site is LIVE + verified** (day 3 of go-live). RESOLVED the deployed 500
+  "Failed to fetch contact" (missing server env at runtime): confirmed the full root cause with git
+  evidence — the inherited `amplify.yml` (from the old `info` repo, which COMMITS its real `.env`
+  files to git) did `cp .env.production .env.local` with cases only for `_production`/`_beta`, but
+  BDR correctly gitignores `.env`, so the `cp` copied nothing and `_dev-sandbox` had no case →
+  zero server env vars per deploy. Fix (commit `e17d804`, branch-agnostic): build-time
+  `env | grep -E '^(HUBSPOT_|TOGA_|NEXT_PUBLIC_|RATE_LIMIT_)' >> .env.production || true`. Recorded
+  the exact **Amplify console recipe** that completed it (Hosting → Environment variables → Manage
+  variables, all branches; the 7 vars incl. new `TOGA_WORKER_URL=https://worker.togahub.com/`;
+  `TOGA_PUBLIC_TOKEN_URL`/`NEXT_PUBLIC_ENV` intentionally dropped) and two new operational gotchas
+  (a console buildspec OVERRIDES the repo `amplify.yml`; adding a custom domain does NOT trigger a
+  rebuild). Verified live: `https://bdr.dev.sandbox.togatech.com/` = 200 and
+  `GET /api/contact?hsContactId=131770626674` = 200 contact JSON. Added a HIGH security gotcha that
+  the old `info` repo commits real HubSpot/Toga credentials to git (treat as compromised; rotation
+  ticket now covers them alongside the worker2 Vapi bearer). STILL PENDING (deferred): the deployed
+  **Call Now** smoke test = fast dial's first live run end-to-end. (tcox)
 - 2026-07-21 — **First Amplify deployment** (app now EXISTS: branch `_dev-sandbox` →
   `dev-sandbox.d65bvvjrww97g.amplifyapp.com`, superseding the "not deployed yet" status).
   DISCOVERED + FIXED (`amplify.yml`, commit `e17d804`) an env-var build-spec bug: the old spec only

package/knowledge/2.0/apps/dbchanges2/architecture.md

@@ -180,6 +180,15 @@ its own header.)
    (`Core/2026-05-08 … CronJobs_WorkerCleanup_insert`) used `UUID()` — that is a known violation,
    not a precedent to copy. First applied correctly in
    `Core/2026-07-21b - Insert - SprintLockScheduled CronJob.sql`.
+7. **Guard every registration/seed insert with `NOT EXISTS` (or `INSERT IGNORE`).** Rows that
+   register platform behavior — `ApiPayloadInterceptors`, `Core.RecordFields`/`CustomRecordFields`,
+   cron jobs, ACL rows — must be inserted only if not already present. An **unguarded** registration
+   is not merely non-idempotent: on a fresh environment it can run **alongside a second migration
+   that registers the same behavior**, producing a **double registration** (e.g. two interceptor
+   rows for the same record → the interceptor fires twice). A real instance: the Rate WH
+   `prePost` interceptor is registered unguarded in `Client_Rate/2026-07-15 - PreInterceptor.sql`
+   (record 191, `minDepth NULL`); a second guarded registration would have double-fired it. See
+   `clients/rate/features/whole-home-warranty-purchase-guard.md`.
 
 ## Bulk data loads — batch, and stage large sets in a temp table
 

package/knowledge/2.0/apps/worker2/features/vapi-webhook-handler.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-21
+updated: 2026-07-23
 owners: [snaredla, tcox]
 files:
   - worker2/Worker/Vapi.php
@@ -239,6 +239,10 @@ The outbound dialer `Worker/Ai/Bdr/Vapi.php` (**line 6**) declares the Vapi API
 rotate it**, and move it into the `[vapi]` section of the worker2 `Config/*.ini` files alongside the
 other Vapi secrets (the pattern the rest of the integration already uses). Config, never source, is
 the home for this credential. (Token value is deliberately not recorded here — location only.)
+**Scope broadened 2026-07-23:** the AI-BDR credential-rotation ticket now also covers the
+**HubSpot access token** and **Toga API client secret** that are committed to git in the old `info`
+repo's tracked `.env.*` files — see the security gotcha in
+[ai-bdr web-funnel-app.md](../../ai-bdr/features/web-funnel-app.md).
 
 ## Data model
 
@@ -267,6 +271,11 @@ status. See the `ai-bdr` skill / `_Model_True_ContactAttempt` for the full field
 - [VAPI Integration — assistants, tools, structured output](../../ai-bdr/features/vapi-integration.md)
 
 ## Change history
+- 2026-07-23 — Broadened the SECURITY credential-rotation gotcha: the AI-BDR rotation ticket now
+  also covers the **HubSpot access token** and **Toga API client secret** committed to git in the
+  old `info` repo's tracked `.env.*` files (treat as compromised), alongside the hardcoded Vapi
+  bearer at `Worker/Ai/Bdr/Vapi.php:6`. Cross-linked to the ai-bdr web-funnel-app security gotcha.
+  (tcox)
 - 2026-07-21 — Full call loop **proven end-to-end in production** on the real campaign 2
   (`26.05 - AI BDR - Ryan Nitti`): UI submit → funnel API → dialer → Vapi call → webhook write-back.
   Live-verified the documented behavior: the `SCHEDULE_CALLBACK` → `c_callOutcome=CALLBACK_SCHEDULED`

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 | > **⚠ BETA-VERIFIED, NOT IN PRODUCTION (as of 2026-07-17).** TRUE-79533 is now merged to > `_beta` (both `_underscore` and `dbchanges2`), applied to the beta `C | _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 | > **⚠ 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, 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

@@ -6,12 +6,14 @@ project: _Underscore
 client: rate
 type: client-feature
 status: draft
-updated: 2026-07-17
+updated: 2026-07-23
 owners: [mhammontree]
 files:
   - _underscore/Model/Rate/Entitlement.php
+  - _underscore/Model/Client/Entitlement.php
   - _underscore/Model/Client/Address.php
-  - dbchanges2/Client_Rate/2026-07-07a - WholeHomeWarrantyPerAddressGuard.sql
+  - dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql
+  - dbchanges2/Core/2026-07-22a - EntitlementServiceAddressIdField.sql
   - test/@Mark/Rate/verify_wholehome_per_address_guard.php
 related:
   - clients/rate/profile.md
@@ -19,14 +21,15 @@ related:
   - ../../../2.0/apps/_underscore/features/address-validation.md
 ---
 
-> **⚠ BETA-VERIFIED, NOT IN PRODUCTION (as of 2026-07-17).** TRUE-79533 is now merged to
-> `_beta` (both `_underscore` and `dbchanges2`), applied to the beta `Client_Rate` DB, deployed,
-> and **PM Paulina successfully tested the Whole Home Warranty purchase flow on beta — it works.**
-> It is still **not** merged to `_production`: the `_underscore` + `dbchanges2` `TRUE-79533` PRs to
-> `_production` remain the open path, and the deliberate production promotion is the only remaining
-> step. An earlier belief that it "shipped weeks ago" is incorrect — TRUE-79251 (purchase emails)
-> shipped, this guard did not. See the **shared-interceptor merge hazard** gotcha below and the
-> **beta unblock procedure** note before merging to `_production`.
+> **⚠ 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 is now being promoted to
+> `_production`. **The service-address field was redesigned since the beta build:** it is no
+> longer a Rate-custom `c_serviceAddressId` field — it is now a **standard** `serviceAddressId`
+> FK on the **base** `_Model_Client_Entitlement` (see *How it works* and *Migration* below). Prod
+> launches clean (no pre-existing WH entitlements), so **no backfill ships**. Treat everything
+> below as forward-looking until the production purchase flow is verified. See the
+> **shared-interceptor merge hazard** gotcha and the **dangling-pin** / **unguarded prod
+> interceptor** gotchas before merging to `_production`.
 
 ## Summary
 
@@ -50,7 +53,7 @@ consistent with `resolvePurchaseProduct`), the guard:
    `hasActiveWarrantyAtAddress()`.
 
 `postPost` then persists the validated service address after save (sets `Addresses.isValidated=1`
-and `Entitlements.c_serviceAddressId`), wrapped so it never blocks the existing AIG-contract /
+and `Entitlements.serviceAddressId`), wrapped so it never blocks the existing AIG-contract /
 confirmation-email flow.
 
 Ticket: TRUE-79533. Business rule owner: PM Paulina.
@@ -64,9 +67,11 @@ Ticket: TRUE-79533. Business rule owner: PM Paulina.
 - **Address line2 distinguishes units.** A landlord's apartment units are distinct addresses:
   2A / 2B / 2C = three separate WHs. Uniqueness keys on the full normalized address including
   line2.
-- **Persist the validated address ON the entitlement** (new `c_serviceAddressId` FK) rather
-  than deriving it from the fragile contact-primary-address path, and **backfill** existing WH
-  entitlements so the global rule covers production data already present.
+- **Persist the validated address ON the entitlement** (via the `serviceAddressId` FK) rather
+  than deriving it from the fragile contact-primary-address path. **No backfill ships** —
+  production launches with no pre-existing WH entitlements, so there is nothing to backfill (the
+  earlier beta build carried an idempotent backfill; it was dropped with the standard-field
+  redesign).
 
 ## How it works
 
@@ -78,25 +83,54 @@ Ticket: TRUE-79533. Business rule owner: PM Paulina.
    the normalized `address1/address2/city/state/zipCode` back onto the payload.
 4. `hasActiveWarrantyAtAddress()` joins `Entitlements` → `Items` (title LIKE `%warranty%`, with
    WH `Items.id = 3` as an OR fallback) → **active** `Subscriptions` (`isActive = 1 AND
-   dateCancelled IS NULL`) → `Addresses` on the new `c_serviceAddressId` column. A match → block
-   the second active WH.
+   dateCancelled IS NULL`) → `Addresses`. A match → block the second active WH.
+   - **The address is resolved via `COALESCE(serviceAddressId, contact's primary address)`**
+     (CodeRabbit hardening). When `serviceAddressId` is set it wins; when it is NULL the query
+     falls back to the contact's primary address (LEFT JOIN `Contacts` → `ContactAddresses`).
+     This means an **unpinned** WH — e.g. one whose `postPost` pin silently failed, leaving
+     `serviceAddressId` NULL — is **still caught** by the dedup. The fallback was chosen over
+     making the `postPost` pin throw, preserving the "never block the save" design.
    - **The dedup read disables the query cache** (`_Database::useQueryCache(false)`, restored in
      a `finally`) so it sees rows committed by a just-prior purchase rather than a stale cached
      result set.
 5. **`postPost`.** After save, persists the validated service address: sets
-   `Addresses.isValidated = 1` and writes `Entitlements.c_serviceAddressId`. This block is
+   `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`).
 6. All SQL uses `_Database::escape()` / int-casts — `_Query` has **no bind API** in this path.
 
-## Migration (`dbchanges2/Client_Rate/2026-07-07a - WholeHomeWarrantyPerAddressGuard.sql`)
+## Field & model: `serviceAddressId` is now a STANDARD field (reviewer Jeff)
 
-- Adds `Entitlements.c_serviceAddressId INT NULL` + an index.
-- Guarded (`NOT EXISTS`) registration of `CustomRecordFields` for `c_serviceAddressId`
-  (recordId 191, type **NUMBER**).
-- Guarded registration of the `ApiPayloadInterceptors` PRE/POST rows.
-- A one-time, idempotent backfill of `c_serviceAddressId` for existing WH entitlements, sourced
-  from `Contacts` → `ContactAddresses` → `Addresses`.
+The service-address field was **promoted from a Rate-custom field to a platform standard field**
+during backend review (Jeff). This is the single biggest change since the beta build:
+
+- **Model.** `serviceAddressId` is declared as an **FK on the BASE `_Model_Client_Entitlement`**
+  (`_underscore/Model/Client/Entitlement.php`) — `[FIELD_FOREIGNKEY, FIELDOPT_FOREIGNKEY_MODEL =>
+  '\_Model_Client_Address']` — not on `_Model_Rate_Entitlement`. The old `c_serviceAddressId`
+  declaration was removed from the Rate subclass. Because api2 resolves the related Addresses
+  model from the FK declaration, declaring it as a proper FK (vs. a plain integer) is what lets
+  the frontend/API traverse to the address.
+- **Core RecordField (standard, not custom).** Registered in **`Core.RecordFields`** on the
+  Entitlements record (**id 191**): type **NUMBER**, `isIdentifier 0`, `childPolicy MATCH`,
+  `precision 0` — mirroring sibling FKs `saleItemId` / `vendorId`. Note `Core.RecordFields` has
+  **no `foreignRecordId` column**; FK resolution is model-side (the model declaration above),
+  not in the RecordField row.
+
+## Migrations (standard-field fan-out — replaces the deleted Rate-only migration)
+
+- **`dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql`** — a **`Client/` fan-out**
+  (every tenant's `Client_<Tenant>.Entitlements`) adding `serviceAddressId INT UNSIGNED` with
+  index `idx_Entitlements_serviceAddressId`, positioned `AFTER subscriptionId`. Because the field
+  lives on the **base** model, **every** client's Entitlements table must have the column, so it
+  is a `Client/` fan-out, not a `Client_Rate/` change.
+- **`dbchanges2/Core/2026-07-22a - EntitlementServiceAddressIdField.sql`** — registers the
+  `Core.RecordFields` row for `serviceAddressId` on record 191, guarded (`NOT EXISTS`).
+- **Deploy order matters:** the column migration must reach **all tenants before** the
+  `_underscore` code that references `serviceAddressId` — otherwise every client breaks.
+- **`dbchanges2/Client_Rate/2026-07-07a - WholeHomeWarrantyPerAddressGuard.sql` is DELETED.** Its
+  column + `CustomRecordFields` moved to the standard field above; its `ApiPayloadInterceptors`
+  registration was redundant (see the **unguarded prod interceptor** gotcha) and its backfill was
+  dropped (prod launches clean).
 
 ## Rate data model (prod-verified 2026-07-07)
 
@@ -105,9 +139,10 @@ Ticket: TRUE-79533. Business rule owner: PM Paulina.
 - **Active-subscription signal is on `Subscriptions`** (`isActive` tinyint default 1,
   `dateCancelled`, `dateEnd`, `dtRequestToCancel`). `Entitlements` has **no `isActive`**.
 - **Entitlements had no address linkage before this ticket.** `SalesOrders` has
-  `shipToAddressId`/`billToAddressId` but they are NULL for Rate. Before `c_serviceAddressId`,
+  `shipToAddressId`/`billToAddressId` but they are NULL for Rate. Before `serviceAddressId`,
   the address was reachable only via `Entitlement.contactId` → `Contacts.primaryContactAddressId`
-  → `ContactAddresses.addressId` → `Addresses`.
+  → `ContactAddresses.addressId` → `Addresses` (this is exactly the COALESCE fallback path the
+  dedup still uses when `serviceAddressId` is NULL).
 - **Borrower identity** = `Customers.c_borrowerId`.
 - **Core.Records record IDs:** Addresses = 13, Entitlements = 191, Sales orders = 14,
   Entitlement tickets = 212.
@@ -186,13 +221,42 @@ 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).
-- **`CustomRecordFields.type` enum supports only `STRING`/`NUMBER`** — `c_serviceAddressId` is
-  registered as `NUMBER`.
+- **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
+  through. On **beta this actually happened** through test-data churn: one reused test contact
+  (`contactId 8`) with addresses created/deleted per purchase left dangling pins, so **manual
+  repeat-purchase testing on beta is unreliable**. Test the dedup with a **fresh contact** or the
+  deterministic `verify_wholehome_per_address_guard.php` script. Prod launches clean (no
+  pre-existing WH entitlements), so no dangling-pin backfill is needed.
+- **The WH `prePost` interceptor is ALREADY registered in production — via an UNGUARDED insert.**
+  `dbchanges2/Client_Rate/2026-07-15 - PreInterceptor.sql` (author rgirish97) registers the
+  record-191 PRE/POST interceptor with `minDepth NULL` and **no `NOT EXISTS` guard**. This is why
+  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.**
+- **`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`.
 - **No `_Query` bind API here** — use `_Database::escape()` / int-casts for all interpolated
   values.
 
 ## Change history
 
+- 2026-07-23 — **Service-address field promoted CUSTOM → STANDARD** (TRUE-79533, reviewer Jeff)
+  and CodeRabbit hardenings, deploying beta→prod. `c_serviceAddressId` on `_Model_Rate_Entitlement`
+  is gone; `serviceAddressId` is now an FK on the **base** `_Model_Client_Entitlement`, registered
+  as a standard `Core.RecordFields` row on record 191 (mirrors `saleItemId`/`vendorId`; no
+  `foreignRecordId` — FK resolution is model-side). Migrations changed to a `Client/` fan-out
+  (`2026-07-22a` adds the column to every tenant) + `Core/2026-07-22a` (RecordField); the Rate-only
+  `Client_Rate/2026-07-07a` was **deleted** (column/field moved to standard, its interceptor
+  registration redundant, backfill dropped — prod launches clean). Guard hardened: `serviceAddressId`
+  declared a proper FK so api2 resolves Addresses; `hasActiveWarrantyAtAddress()` now resolves via
+  `COALESCE(serviceAddressId, contact primary address)` so an unpinned WH is still deduped. Recorded
+  the **dangling-pin** gotcha (deleted-address pin makes an entitlement invisible to the dedup;
+  beta test-data churn on `contactId 8`) and the **unguarded prod interceptor** gotcha
+  (`Client_Rate/2026-07-15 - PreInterceptor.sql` registers record-191 PRE/POST with no `NOT EXISTS`
+  → double-register risk; add a guard). (mhammontree)
 - 2026-07-17 — **Beta-verified** (TRUE-79533): corrected code merged to `_beta` (`_underscore` +
   `dbchanges2`), `2026-07-07a` migration applied to the beta `Client_Rate` DB, beta redeployed, and
   **PM Paulina successfully tested the WH purchase flow on beta.** Recorded the **beta unblock

package/package.json

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