toga-ai 1.0.489 → 1.0.490

package/knowledge/2.0/apps/_underscore/INDEX.md

@@ -5,7 +5,8 @@
 | [Proposed — git-sourced base+overlay JSON authoring for the Surface layer](architecture/surface-authoring-proposal.md) | A **proposal / handoff recommendation** (not implemented) that the Surface layer's *authoring* model move off hand-authored SQL against the `SurfaceOverrides` E | _underscore/Model/Core/Surface.php, _underscore/Model/Client/SurfaceOverride.php |
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
 | [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, _underscore/Model/Client/TrackingNumber.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission.sql, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql |
-| [Address Validation (carrier waterfall + validateAddress scripted endpoint)](features/address-validation.md) | `_Model_Client_Address::validateAddress` verifies a US address against a **carrier waterfall (USPS → FedEx → UPS)** and returns a single canonical, carrier-norm | _underscore/Model/Client/Address.php |
+| [Address Uniqueness Normalization (unit identifier + 5-digit ZIP comparison)](features/address-uniqueness-normalization.md) | When a business rule says *"only one X per physical address"*, comparing address rows field-for-field does **not** work: the same dwelling is spelled many diffe | _underscore/Model/Rate/Entitlement.php |
+| [Address Validation (carrier waterfall + validateAddress scripted endpoint)](features/address-validation.md) | `_Model_Client_Address::validateAddress` verifies a US address against a **carrier waterfall (USPS → FedEx → UPS)** and returns a single canonical, carrier-norm | _underscore/Model/Client/Address.php, _underscore/Component/Library/Carriers/Usps/Usps.php |
 | [_ApiRequest — JSON encode/decode & api-logging behavior](features/apirequest-json-content-type.md) | `_ApiRequest` is the 2.0 outbound HTTP client. | _underscore/ApiRequest.php |
 | [Assortment Name Translation (AssortmentTranslations sidecar)](features/assortment-name-translation.md) | Serves Assortment (product-grouping) **names** in multiple languages by adding a per-language **sidecar** table `AssortmentTranslations`, reusing the platform's | _underscore/Model/Client/AssortmentTranslation.php, dbchanges2/Client/2026-06-26a - AssortmentTranslations.sql, dbchanges2/Core/2026-06-26a - AssortmentTranslationsRecord.sql, dbchanges2/Client/2026-06-26b - AssortmentTranslationsAcl.sql |
 | [Asynchronous Query Execution (writes-only, via Worker)](features/async-query-execution.md) | `_Query` can run a **write** query asynchronously so a long/slow write does not hold a request-scoped DB connection open long enough to hit **"MySQL server has | _underscore/Query.php, worker2/Worker/Infrastructure/Database.php, worker2/Worker/Team/Transcripts.php |
@@ -31,5 +32,6 @@
 | [Table-View Hyperlink Columns (meta → ACL → computed URL → render)](features/tableview-hyperlink-columns.md) | Any 2.0 table-view column can render its value as a clickable link instead of plain text. | _underscore/Model/Client/TableView.php, _underscore/Model/Client/TrackingNumber.php, api2/Component/Api/V2/V2.php, toga2-supply/src/api/toga.ts, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/formatTableData.tsx, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/convertData.tsx, toga2-supply/src/components/ui/Tables/hooks/useDataTableState.tsx, dbchanges2/Client/2026-07-20 - TrackingNumberHyperlinkAndFieldPermission.sql |
 | [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | api2/Component/Api/V2/V2.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19b - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Growrk/2026-07-13a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql |
 | [Units for Items for Purchase Orders — Data Structure](features/units-for-items-for-purchase-orders.md) | Describes how unit (serialized inventory) data is linked to sales-order and purchase-order line items behind the `units-for-items-for-purchase-orders` TableView |  |
+| [USPS DPV Deliverability Verdict (is this address actually insurable/shippable?)](features/usps-dpv-deliverability.md) | **USPS returning HTTP 200 with a populated address is NOT evidence that the address is deliverable.** The authoritative signal is USPS's **DPV (Delivery Point V | _underscore/Component/Library/Carriers/Usps/Usps.php, _underscore/Model/Client/Address.php, _underscore/Model/Rate/Entitlement.php |
 | [Refreshing a Local Dev Database from Beta (dev-sandbox)](workflows/local-db-refresh-from-beta.md) | How to reset a local 2.0 dev database from the **beta / dev-sandbox** environment: dump each schema (`Core`, `Client_<Id>`, `Logs_<Id>`, …) from the beta host, | api2/Config/, _underscore/Loader.php, _underscore/Model/Client/BundleTranslation.php, api2/Component/Api/V2/V2.php, toga25-supply/sync_compasscanada_schema.sql |
 | [Running a 2.0 App Locally (browser, end-to-end via api2)](workflows/running-a-2.0-app-locally.md) | The full dependency chain required to run a 2.0 client app **through the browser**, end-to-end, against a **local `api2`** (e.g. | _underscore/Environment.php, _underscore/Config.php, _underscore/Database.php, _underscore/Route.php, api2/Component/Api/V2/V2.php, api2/Controller/Index.php, api2/index.php, api2/.htaccess |

package/knowledge/2.0/apps/_underscore/features/address-uniqueness-normalization.md

@@ -0,0 +1,96 @@
+---
+title: "Address Uniqueness Normalization (unit identifier + 5-digit ZIP comparison)"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-07-31
+owners: [mhammontree]
+files:
+  - _underscore/Model/Rate/Entitlement.php
+related:
+  - ./address-validation.md
+  - ./usps-dpv-deliverability.md
+  - ../../../clients/rate/features/whole-home-warranty-purchase-guard.md
+---
+
+## Summary
+
+When a business rule says *"only one X per physical address"*, comparing address rows
+field-for-field does **not** work: the same dwelling is spelled many different ways
+(`Suite 500` / `STE 500` / `Ste. 500` / `#500`), and carrier validation returns a **ZIP+4**
+while every legacy row holds 5 digits. This doc records the two normalization primitives
+built for the Rate Whole Home Warranty per-address guard, both of which are **reusable for any
+"one per address" rule** on the platform.
+
+Both live as private helpers on `_Model_Rate_Entitlement` today (first use); promote them to a
+shared helper when a second consumer appears.
+
+## `normalizeUnitIdentifier()` — compare the UNIT, discard the designator
+
+Line 2 is compared by **unit identifier only**. Everything that is not `A–Z0–9` is stripped,
+the result upper-cased, and any leading designator word removed:
+
+| Input `line2` | Normalized unit |
+|---|---|
+| `Suite 500`, `STE 500`, `Ste. 500`, `#500`, `Apt 500`, `No. 500`, `500` | `500` |
+| `4B`, `12A`, `PH2`, `101-A` | `4B`, `12A`, `PH2`, `101A` |
+| `""`, `NULL`, invisible-only (see below) | *(no unit)* |
+
+**Why discard the designator instead of maintaining a synonym list.** Within a single
+`line1 + city + ZIP5`, the designator carries **no distinguishing information** — there is no
+real building with both a "Suite 500" and an "Apt 500". Discarding it removes any synonym
+table to maintain and errs toward **MATCHING**, which is the correct bias for a *uniqueness
+guard* (a false match blocks a purchase and a human resolves it; a false non-match silently
+creates the duplicate the rule exists to prevent).
+
+**An EMPTY unit means "the whole building"** and therefore conflicts with **ANY** unit at the
+same street address, **in both directions**. So a building-wide warranty and a per-unit
+warranty can never coexist.
+
+**`trim()` alone is insufficient.** The `[^A-Z0-9]` strip is what collapses the invisible
+characters that survive `trim()` — NBSP `U+00A0`, ZWSP `U+200B`, ZWJ `U+200D`, BOM `U+FEFF`,
+ideographic space `U+3000`. An invisible-only `line2` normalizes to *no unit*, identical to
+`NULL`, which is the intent.
+
+## `comparableZip()` — compare the first 5 digits only
+
+USPS returns **ZIP+4** (verified live: `60503-7832`) while every pre-existing `Addresses` row
+holds 5 digits. An exact ZIP comparison therefore missed **every legacy row**. Uniqueness
+compares `substr(digits, 0, 5)`.
+
+## Where the comparison happens: SQL narrows, PHP decides
+
+The dedup query narrows candidates on `line1 + city + 5-digit ZIP + state`, and the **unit
+comparison runs in PHP** over the returned candidates.
+
+**Why not do it in SQL.** Real normalization cannot be expressed in SQL without a nested
+`REPLACE()` chain, which is both unreadable and **unindexable** (no index can serve it, so it
+degrades to a full scan). Narrow in SQL on indexable columns, then compare in PHP.
+
+The candidate fetch is capped at **`DEDUP_CANDIDATE_LIMIT = 500`** with an `error_log` canary
+if the cap is ever hit — a single street address with 500+ address rows means something else
+is wrong.
+
+## Gotchas / known issues
+
+- **Never judge address duplication from a query that omits `line2`.** During this session
+  three beta entitlements looked like duplicates on a `line1 + zip` projection and were in
+  fact **distinct units** (`STE 1900` / `# 4` / `STE 500`). Always select `line2` before
+  concluding two addresses are the same — and certainly before deleting anything.
+- **Bias is deliberately toward matching.** If a legitimate distinct unit is ever blocked, fix
+  it by making the *guard's* message actionable, not by adding designator sensitivity back.
+- **Promote before the second copy.** These helpers are Rate-private only because Rate is the
+  first consumer. Copy-pasting them into a second client model is how normalization rules
+  drift apart.
+
+## Change history
+- 2026-07-31 — Built `normalizeUnitIdentifier()` (designator-discarding unit comparison,
+  invisible-character collapse, empty-unit-conflicts-with-everything semantics) and
+  `comparableZip()` (5-digit comparison, because USPS returns ZIP+4 and legacy rows hold 5)
+  for the Rate WH per-address guard (TRUE-80487). Recorded the SQL-narrows/PHP-decides split
+  (real normalization is unindexable in SQL), `DEDUP_CANDIDATE_LIMIT = 500` + canary, and the
+  "never judge duplication without `line2`" lesson from three beta rows misread as duplicates.
+  (mhammontree)

package/knowledge/2.0/apps/_underscore/features/address-validation.md

@@ -6,13 +6,16 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-07
+updated: 2026-07-31
 owners: [mhammontree]
 files:
   - _underscore/Model/Client/Address.php
+  - _underscore/Component/Library/Carriers/Usps/Usps.php
 related:
   - ../../api2/features/scripted-api-post-body-args.md
   - ../../api2/architecture.md
+  - ./usps-dpv-deliverability.md
+  - ./address-uniqueness-normalization.md
   - ../../../clients/rate/features/whole-home-warranty-purchase-guard.md
 ---
 
@@ -34,6 +37,16 @@ Whole Home Warranty purchase guard).
     `zip4`/`zip5`.
   - **On failure** (all carriers fail) returns the **last (UPS) response** with
     `success:false` (and an `error`).
+  - **Since 2026-07-31** the USPS leg also returns `DPVConfirmation`, `vacant`, `business` and
+    `corrections[]`, and `_Model_Client_Address` exposes `DPV_*` constants +
+    `withValidationDefaults()` — see
+    [USPS DPV deliverability](./usps-dpv-deliverability.md).
+
+> **`success:true` does NOT mean the address is deliverable.** USPS returns HTTP 200 with a
+> populated address even when the secondary unit is **missing or invented**. Any caller whose
+> business rule depends on the address being real (insurance, warranty, shipment to a unit)
+> must read the **DPV verdict**, not just `success`. See
+> [USPS DPV deliverability](./usps-dpv-deliverability.md).
 
 ## The scripted endpoint is registered in the DB, not in source (parity gap)
 
@@ -68,8 +81,19 @@ in `dbchanges2` source** (closing the parity gap noted below) rather than only i
   distinct from the older global `validateAddress` route's `data.addresses.validateAddress`).
 
 The PHP method (`_Model_Client_Address::validateAddress`) already existed and was unchanged — it was
-simply **unrouted in source** until this migration set exposed it. New scripted routes should follow
-this pattern (route + `AclRecordScripts` both in `dbchanges2`).
+simply **unrouted in source** until this migration set exposed it.
+
+> **⚠ CORRECTION (2026-07-31): that grant migration never took effect.**
+> `Client/2026-07-16c - AddressValidateScriptAcl.sql` **silently no-ops** — Core script **28**
+> (`addresses/validate`) has **ZERO** `AclRecordScripts` rows in `Client_Rate`. The file resolves
+> the Core script id with a cross-database `Core.*` read from a fan-out `Client/` folder, which
+> cannot work: in production `Core` is a **separate cluster**, and on a developer machine the
+> literal schema `Core` is the **1.0** database (the 2.0 core is `Core_2`) which has no
+> `RecordScripts` table at all. Either way the `SET @var` stays NULL and the `NOT EXISTS`-guarded
+> INSERT inserts nothing. **Do not copy this file as the pattern.** For a *client-specific*
+> scripted API, register it as a **client-side `CustomRecordScripts`** instead — registration and
+> grant then live in one database (see
+> [Record Scripts → client-side CustomRecordScripts](../../api2/features/record-scripts.md)).
 
 ## Client variations
 
@@ -83,8 +107,37 @@ per the standard client carrier config.
   migrations into a fresh DB. Register scripted endpoints in `dbchanges2` going forward.
 - **Waterfall requires agreement on success.** The success shape is only returned when the
   carriers agree; a `success:false` result carries the last (UPS) response, not a merged one.
+- **Scripted-API parity gaps (audited 2026-07-31).** Source and live DB disagree in both
+  directions — verify against the live `Core.RecordScripts` rows, never source alone:
+  - **`addresses/validateAddress` (id 17), the endpoint `toga2-view` actually calls, exists ONLY
+    as a live DB row** — there is **no `dbchanges2` migration for it**. A freshly provisioned
+    environment would **404** on the endpoint the frontend depends on.
+  - **`tracking-numbers/reprint` is MISSING ENTIRELY from production `Core.RecordScripts`** — so
+    `Core/2026-07-01a - TrackingNumberReprintRecordScript.sql` never took effect in production.
+  - **`addresses/validate` (id 28) has zero `AclRecordScripts` grants in `Client_Rate`** (see the
+    correction above).
+- **`Core.RecordScripts` ids are NOT stable across environments** — max id is 27 in production,
+  28 local, 28 client-sandbox, 30 dev-sandbox, and the *same* script has different ids per
+  environment. Never hardcode a `RecordScripts` id, and never assume "the next available id"
+  means the same thing anywhere else. (`Core.Records` ids, by contrast, **are** seeded
+  identically everywhere — Addresses = 13.)
+- **USPS OAuth credentials are committed in plaintext** in
+  `_underscore/Component/Library/Carriers/Usps/Usps.php` (constants near the top of the file);
+  they belong in the `_Config` INI. Rotate and relocate — see the
+  [DPV doc](./usps-dpv-deliverability.md). *(Location only; no value recorded.)*
 
 ## Change history
+- 2026-07-31 — TRUE-80487: recorded that **`success:true` does not mean deliverable** (USPS
+  returns 200 for a missing/invented unit) and split the DPV verdict out into
+  [usps-dpv-deliverability.md](./usps-dpv-deliverability.md); the USPS leg now also returns
+  `DPVConfirmation`/`vacant`/`business`/`corrections`. **Corrected the 2026-07-17 entry below:**
+  `Client/2026-07-16c - AddressValidateScriptAcl.sql` **silently no-ops** (script 28 has zero
+  `AclRecordScripts` rows in `Client_Rate`) because it reads `Core.*` from a fan-out `Client/`
+  folder — unreachable in prod (separate cluster) *and* locally (`Core` is the **1.0** DB; the 2.0
+  core is `Core_2`). It is **not** the pattern to copy. Added the audited scripted-API parity gaps
+  (script 17 exists only in the live DB with no migration; `tracking-numbers/reprint` absent from
+  production) and the `Core.RecordScripts` id-drift fact. Also recorded the committed plaintext
+  USPS credential location. (mhammontree)
 
 - 2026-07-17 — TRUE-79191: added a **`dbchanges2`-registered** `GET /addresses/validate` route to the
   same `validateAddress` method (Core `RecordScripts` route `validate` + Client `AclRecordScripts`

package/knowledge/2.0/apps/_underscore/features/usps-dpv-deliverability.md

@@ -0,0 +1,103 @@
+---
+title: "USPS DPV Deliverability Verdict (is this address actually insurable/shippable?)"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-07-31
+owners: [mhammontree]
+files:
+  - _underscore/Component/Library/Carriers/Usps/Usps.php
+  - _underscore/Model/Client/Address.php
+  - _underscore/Model/Rate/Entitlement.php
+related:
+  - ./address-validation.md
+  - ./address-uniqueness-normalization.md
+  - ../../../clients/rate/features/whole-home-warranty-purchase-guard.md
+---
+
+## Summary
+
+**USPS returning HTTP 200 with a populated address is NOT evidence that the address is
+deliverable.** The authoritative signal is USPS's **DPV (Delivery Point Validation)**
+confirmation code, which the carrier waterfall previously **discarded**. This doc records what
+DPV means, the live-verified verdicts, and the platform mapping now applied.
+
+USPS will happily echo back an **invented** secondary unit and still return 200 — so adopting
+the "recommended" address alone does **not** fix a bad unit. **The DPV field must be read.**
+
+## The verdicts (VERIFIED against live USPS responses 2026-07-31)
+
+| Address probed | `DPVConfirmation` | Meaning |
+|---|---|---|
+| `1904 IONE LN, AURORA IL 60503` (no unit) | **`Y`** | deliverable exactly as given |
+| `1904 IONE LN` + `UNIT 200` (invented; single-family) | **`S`** | secondary present but **not confirmed** |
+| `2511 VERSAILLES AVE, NAPERVILLE IL 60540` (no unit) | **`D`** | secondary **MISSING** — building is subdivided |
+| `2511 VERSAILLES AVE` + `# 1` (invalid) | **`S`** | secondary not confirmed |
+
+The `D` case additionally returns `corrections[].code` **`32`** — *"Default address: … more
+information is needed (such as an apartment, suite, or box number)."*
+
+**Platform mapping:**
+
+| DPV | Action |
+|---|---|
+| `Y` | proceed |
+| `D` | reject — **unit required** |
+| `S` | reject — **unit not verified** |
+| `N` | reject |
+| `''` / absent | **unknown → PROCEED** (see decision below) |
+
+## DECIDED: unknown DPV proceeds (fails OPEN, deliberately)
+
+FedEx and UPS — the waterfall's fallbacks — **do not report DPV at all**. If a fallback carrier
+answered, the DPV verdict is unknown. That case **proceeds**: failing closed would block
+**every** purchase during a USPS outage, and for the uniqueness use case the
+[dedup guard](./address-uniqueness-normalization.md) still prevents duplicates independently.
+This is a conscious availability-over-strictness trade; do not "harden" it without a
+business-owner decision.
+
+## What was captured
+
+- **`Usps.php`** now captures `DPVConfirmation`, `vacant`, `business`, and `corrections[]` off
+  the USPS response. `vacant` and `business` are **free** in `additionalInfo` and are now
+  carried through as potential underwriting inputs (no rule consumes them yet).
+- **`_Model_Client_Address`** gained `DPV_*` constants plus **`withValidationDefaults()`**,
+  which is **purely additive**: it is implemented as `$response + [defaults]`, so the **left
+  operand wins** and a real carrier verdict can never be clobbered by a default.
+
+## Carriers cannot tell you DWELLING TYPE
+
+A recurring ask ("is this an apartment building?") is **not answerable from carrier data**:
+
+- UPS `AddressClassification` and FedEx classification only distinguish **Residential vs
+  Commercial** — an apartment building is *Residential*.
+- The only actionable signal available is USPS DPV **"secondary unit required"** (`D`).
+- **True dwelling type requires property data** — an assessor/parcel feed or a
+  Melissa/Smarty-class vendor. That is a **procurement decision, not a code one.**
+
+## Gotchas / known issues
+
+- **HTTP 200 ≠ deliverable.** This is the whole point of the doc. Success + a populated
+  address is the *normal* response for a missing or invented unit.
+- **USPS does not strip an invented unit.** It echoes `UNIT 200` back verbatim. Adopting the
+  recommended address does not sanitize it.
+- **Plaintext USPS OAuth credentials are committed in source** — the client id and secret are
+  hardcoded as constants near the top of
+  `_underscore/Component/Library/Carriers/Usps/Usps.php`. They belong in the `_Config` INI
+  alongside the DB credentials. **Treat them as compromised: rotate and move to SSM / EB
+  environment properties.** Pre-existing, not introduced by this work. *(Location +
+  remediation only — no value is recorded anywhere.)*
+
+## Change history
+- 2026-07-31 — Discovered that the carrier waterfall was **discarding** USPS DPV, and built
+  capture + enforcement (TRUE-80487): `Usps.php` now returns `DPVConfirmation`/`vacant`/
+  `business`/`corrections`, `_Model_Client_Address` gained `DPV_*` constants and the additive
+  `withValidationDefaults()`, and Rate's WH guard enforces `Y` proceed / `D` unit-required /
+  `S` unit-unverified / `N` reject / unknown proceed. Verdicts verified against four live USPS
+  probes; recorded that USPS echoes an invented unit back with a 200, that unknown DPV fails
+  **open** by decision, and that carriers cannot supply dwelling type (only Residential vs
+  Commercial) so an apartment-vs-house rule needs property data. Also recorded the committed
+  plaintext USPS OAuth credential location for rotation. (mhammontree)

package/knowledge/2.0/apps/api2/INDEX.md

@@ -20,5 +20,5 @@
 | [V2 API error/message codes (EV/EZ troubleshooting map)](features/v2-api-error-codes.md) | The V2 JSON engine (`Component/Api/V2/V2.php`) returns short **message codes** in the response `error` field, grouped by family: `EN-*` authentication, `EZ-*` a | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, api2/Component/Api/V2/Response/Oauth/Oauth.php, api2/Controller/Index.php, toga2-supply/src/globalTypes.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, _underscore/Model/Client/TrackingNumber.php |
 | [V2 REST query contract (params, where grammar, encoding, ACL behavior)](features/v2-rest-query-contract.md) | What an **HTTP client** has to get right to query the Toga v2 REST API: which query params are recognized, the exact `where` grammar, how the query string is (n | api2/Component/Api/V2/V2.php |
 | [V2 reverse hasMany collections must be named in the fetch fields whitelist](features/v2-reverse-hasmany-fields-whitelist.md) | In the V2 JSON engine, a **reverse hasMany** relationship — the collection of child records that foreign-key back to a parent (e.g. | api2/Component/Api/V2/V2.php |
-| [AWS CodePipeline Deployment via CodeConnections (GitHub → Elastic Beanstalk)](workflows/codepipeline-codeconnections-deploy.md) | 2.0 apps (`api2`, `_underscore`) are deployed through **AWS CodePipeline**. | api2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, api2/ebs/register_instance_to_shared_application_load_balancer.php |
+| [AWS CodePipeline Deployment via CodeConnections (GitHub → Elastic Beanstalk)](workflows/codepipeline-codeconnections-deploy.md) | 2.0 apps (`api2`, `_underscore`) are deployed through **AWS CodePipeline**. | api2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, api2/ebs/register_instance_to_shared_application_load_balancer.php, api2/.platform/hooks/prebuild/git.sh, api2/.ebextensions/git.php, api2/.ebextensions/git.sandbox-dev.json |
 | [New Environment Configuration & Provisioning (api2)](workflows/environment-configuration-and-provisioning.md) | What it takes for a 2.0 API environment (e.g. | api2/Config/<environment>.ini, api2/Controller/Index.php, dbchanges2/Core/2026-06-16a - DatabaseHosts for new QA QC stage demo environments.sql, dbchanges2/Logs/, _underscore/Route.php |

package/knowledge/2.0/apps/api2/features/record-scripts.md

@@ -136,6 +136,56 @@ metadata model.
   endpoint goes in `Client_True`. The generic **`Client/`** folder runs against **every**
   tenant DB, so putting an ACL grant there hands the endpoint to all clients.
 
+> **⚠ The "resolve the Core id by route from the client file" convention above is NOT runnable
+> for the `AclRecordScripts` grant.** `AclRecordScripts.recordScriptId` links to
+> `Core.RecordScripts` by **NUMERIC id** (there is no uuid reference column), so a `Client_*`
+> migration must read `Core` to resolve it — which is impossible in production (separate
+> clusters) **and equally broken in local dev**: locally the 2.0 core schema is **`Core_2`**, and
+> the schema literally named `Core` is the **1.0** database, which has no `RecordScripts` and no
+> `RecordFields`. So a literal `Core.<Table>` reference resolves to the wrong (or missing) schema
+> in *both* environments, and a `NOT EXISTS`-guarded INSERT inserts nothing without erroring.
+> **A clean local run is therefore never proof that such a migration worked.** This is not
+> theoretical: `Client/2026-07-16c - AddressValidateScriptAcl.sql` **silently no-ops**, leaving
+> Core script 28 with zero grants in `Client_Rate`. For a **client-specific** script, use the CustomRecordScripts pattern below.
+
+## ✅ REUSABLE PATTERN — register a CLIENT-SPECIFIC scripted API as a `CustomRecordScript`
+
+**When a scripted API is declared on a client model (`_Model_<Slug>_X`), register it in the
+CLIENT database as a `CustomRecordScript` — NOT in `Core.RecordScripts`.** First applied in
+`dbchanges2/Client_Rate/2026-07-31a - WarrantyAvailabilityCustomRecordScript.sql`
+(`_Model_Rate_Entitlement::warrantyAvailability`).
+
+**Why (three independent reasons):**
+
+1. **One database, so the grant is resolvable.** `CustomRecordScripts` **and**
+   `AclCustomRecordScripts` are **both** `DB_CLIENT`
+   (`_Model_Client_CustomRecordScript` / `_Model_Client_AclCustomRecordScript`). Registration and
+   grant therefore live in the **same** database, and the grant can resolve the script id from a
+   **hardcoded v4 UUID literal** via a same-database lookup — **no id needs pinning and no
+   cross-team coordination is required.** A `Core.RecordScripts` registration puts the id in
+   `Core` while the grant lives in the client DB and links by numeric id, forcing exactly the
+   impossible cross-tenant read described above.
+2. **api2 reads both from `DB_CLIENT`.** In `api2/Component/Api/V2/V2.php`, the
+   `lookupCustomRecordScriptsByRecordIdAndMethodAndRoute` map is built from
+   `SELECT … FROM CustomRecordScripts` (~line 8613) and authorization goes through
+   `AclCustomRecordScripts` (~line 5919). **`Core.RecordScripts` are checked FIRST, with a
+   fallback to custom** (~line 5906) — so a custom script cannot shadow a global one, and a
+   global one always wins.
+3. **It is semantically correct.** The method is declared on the *client* model, not the base
+   model. Registering it in `Core` would advertise the route to **every** tenant, including
+   tenants whose model has no such method.
+
+**Authoring notes from the first use:**
+- `recordId` is written as the **literal** (191 for Entitlements) per team convention —
+  `Core.Records` ids **are** deliberately seeded identically in every environment
+  (Addresses 13, Sales orders 14, Entitlements 191, Subscriptions 253). This is safe;
+  `Core.RecordScripts` ids are **not** (they have drifted per environment).
+- **Grant `Base` only, resolved by NAME** — role ids differ per client.
+- **Do NOT grant `Public`.** A warranty-availability endpoint reveals whether a warranty exists
+  at an arbitrary address; unauthenticated probing must be prevented.
+- Verified by applying the file **twice** to two environments: exactly one script row and one
+  grant row each.
+
 ## Data source note (core DB hosts/credentials)
 
 The core cluster hosts and credentials this endpoint reads through are **not** documented here;
@@ -149,6 +199,12 @@ an `AclRecordScripts` grant in each client DB.
 
 ## Gotchas / known issues
 
+- **The response key is the ROUTE VERBATIM, not the `phpMethod`.** A script registered with
+  route `warranty-availability` and `phpMethod` `warrantyAvailability` returns
+  **`data.entitlements["warranty-availability"]`** — *not* `data.entitlements.warrantyAvailability`.
+  The sibling `addresses/validateAddress` reader looks camelCase only because **that script's
+  route is itself `validateAddress`.** Reading the wrong key yields `undefined` (and, in a
+  fail-closed consumer, correctly denies) — this cost a debug cycle in beta.
 - **No bound params in `_Query`.** Sanitize with `\_Database::escape()` (strings) and `(int)`
   casts (numerics) for every value placed into the query text — query-string args are user
   input.
@@ -169,6 +225,20 @@ an `AclRecordScripts` grant in each client DB.
 
 ## Change history
 
+- 2026-07-31 — TRUE-80487: added the **reusable client-side `CustomRecordScript` pattern** for a
+  scripted API declared on a client model — `CustomRecordScripts` + `AclCustomRecordScripts` are
+  **both** `DB_CLIENT`, so registration and grant land in **one** database and the grant resolves
+  the script id from a hardcoded uuid (no id pinning, no cross-team coordination); api2 reads both
+  from `DB_CLIENT` (`V2.php` ~8613 / ~5919) and checks `Core.RecordScripts` **first** with a
+  fallback to custom (~5906). Recorded **why the existing `Core.RecordScripts` + `Client_*`
+  `AclRecordScripts` convention is unrunnable** for a client-scoped script
+  (`AclRecordScripts.recordScriptId` links by numeric id with no uuid reference → forced
+  cross-cluster read; `Client/2026-07-16c - AddressValidateScriptAcl.sql` silently no-ops, script
+  28 has zero grants in `Client_Rate`). Also recorded that the response key is the **route
+  verbatim** (`data.entitlements["warranty-availability"]`, not the camelCase `phpMethod`), that
+  `Core.Records` ids are environment-stable literals while `Core.RecordScripts` ids have drifted,
+  and the grant-Base-by-name / never-Public guidance. First use:
+  `dbchanges2/Client_Rate/2026-07-31a - WarrantyAvailabilityCustomRecordScript.sql`. (mhammontree)
 - 2026-07-24 — Refined the engine contract from productionizing the sprint dashboard (verified
   in `V2.php` + `_underscore/Query.php`): the return value **nests under the route-segment key**
   (`data[<route>]`, not flat — consumers must unwrap); there is **no current-sprint/context

package/knowledge/2.0/apps/api2/workflows/codepipeline-codeconnections-deploy.md

@@ -6,12 +6,16 @@ project: API
 client: shared
 type: workflow
 status: active
-updated: 2026-07-28
+updated: 2026-07-31
 owners: ["jcardinal", "mhammontree"]
 files:
   - api2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh
   - api2/ebs/register_instance_to_shared_application_load_balancer.php
-related: []
+  - api2/.platform/hooks/prebuild/git.sh
+  - api2/.ebextensions/git.php
+  - api2/.ebextensions/git.sandbox-dev.json
+related:
+  - ../../../standards/frontend-deploy.md
 ---
 
 ## Summary
@@ -40,6 +44,27 @@ app-repo `_<env>` branches.
 > this env; you must push it to **`_sandbox-dev`**. Always confirm the exact env↔branch mapping in the
 > env's `git.<env>.json` before assuming `_<env>` applies.
 
+### "beta" is a DIFFERENT git branch per repo — the full map (verified 2026-07-31)
+
+The word *beta* names an **environment**, not a branch, and each tier resolves it differently.
+Getting this wrong cost **two wasted deploys** in one session (TRUE-80487). Confirm the tier you
+are actually changing before you merge anything:
+
+| Tier | What "beta" is | Branch actually built | Notes |
+|---|---|---|---|
+| `api2` / `_underscore` | EB env **`API-Sandbox-Dev`** behind `api.beta.togahub.com` | `_underscore` **`_sandbox-dev`** (per `.ebextensions/git.sandbox-dev.json`) | **Not `_beta`.** Database environment is **`dev-sandbox`**. |
+| `toga2-view` | AWS Amplify target **named "production"** | git branch **`_beta`**, bundling `.env.beta` (`VITE_API=https://api.beta.togahub.com/v2`) | The target *name* is misleading; proven by a string present only in `_beta` appearing in the deployed UI and absent from `_production`. |
+
+- **`Client_Rate` exists in `prod`, `dev-sandbox` and `client-sandbox` — NOT in `client-beta`.** So
+  "the beta database" is ambiguous too; name the concrete DB environment.
+- **`_underscore` is NOT vendored into `api2`.** `.platform/hooks/prebuild/git.sh` +
+  `.ebextensions/git.php` clone it at build time (branch = the per-env json's `branch`, else
+  `_<environment>`). Consequence: **a framework-only change requires REDEPLOYING THE CONSUMING
+  TIER even when `api2` itself has zero changes** — an instance **restart will not pick it up**,
+  because the clone happens in prebuild.
+- **`api2` has no deploy workflow.** Its only GitHub Action is the `TRUE-#####:` commit-message
+  linter, so **EB deploys are manual**. Do not wait for CI to ship a framework change.
+
 ### Debugging a beta env without Sentry — `Logs_<Client>.Api`
 `Logs_<Client>.Api` is a **full server-side request log**: `queryString`, request/response payloads,
 `direction` (`IN`/`OUT`), `instanceId`, and `executionTime`. It is the reliable way to see what a
@@ -139,6 +164,14 @@ aws codeconnections get-connection --connection-arn "<CONN_ARN>" --region "$REGI
 ```
 
 ## Change history
+- 2026-07-31 — TRUE-80487: added the **full cross-tier "beta" environment map** after it cost two
+  wasted deploys. `api.beta.togahub.com` is EB env **`API-Sandbox-Dev`** on the **`dev-sandbox`**
+  database, cloning `_underscore` **`_sandbox-dev`**; `toga2-view`'s Amplify target **named
+  "production"** actually builds branch **`_beta`** with `.env.beta` pointing at that API. Recorded
+  that `Client_Rate` exists in prod/dev-sandbox/client-sandbox but **not** client-beta, that
+  `_underscore` is cloned in **prebuild** (so a framework-only change needs the consuming tier
+  **redeployed**, not restarted), and that `api2` has **no deploy workflow** — EB deploys are
+  manual. (mhammontree)
 - 2026-07-28 — Manual LB re-registration is now automated on **non-production** tiers carrying the `.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh` hook pair (api2 already had it; ported to worker2 this session). Linked the new worker2 feature doc as the reference implementation and flagged that api2's copy has known security defects. (jcardinal)
 - 2026-07-27 — Noted that not every EB env pulls `_underscore` from its `_<env>` branch: **`API-Sandbox-Dev`** re-clones `_underscore` from the branch in `.ebextensions/git.sandbox-dev.json` (**`_sandbox-dev`**), overwriting the pipeline copy — so a `_beta` merge doesn't reach it. Added the `Logs_<Client>.Api` server-side request-log note as the reliable way to debug a beta env without Sentry (TRUE-79533). (mhammontree)
 - 2026-07-14 — Documented the branch model: app repos (`_underscore`/`api2`/`toga2-supply`) deploy from long-lived `_beta`/`_production` branches (not `_main`); api2 pulls `_underscore`'s `_<env>` branch at EB build; `dbchanges2` has only `_main` and its migrations are applied per-env by the team process (not by a code deploy). (mhammontree)

package/knowledge/2.0/apps/dbchanges2/features/surface-layer-schema.md

@@ -467,6 +467,27 @@ rule resumes.
   earlier `2026-06-25c` / `2026-06-29c` / `2026-06-25d` surface seeds **likely share the same
   anti-pattern** and need auditing. Core→Core seeds are fine (same cluster). Also still open:
   re-seeding NYCHH/Prudential/SPGlobal (deferred).
+  - **✅ AUDIT DONE (2026-07-31, TRUE-80487) — and the failure is WORSE, but the fix is CHEAPER
+    than assumed.** A full sweep of `dbchanges2` found **24 of 505 non-`HISTORIC` `.sql` files**
+    referencing a database outside their folder's tenant (comment-only mentions excluded): **13 in
+    `Client/`** — including `2026-06-03 BLANK_CLIENT_DATABASE`, the **new-client template** — **3
+    in `Client_Rate/`**, **2 in `Core/` reaching into `Client.*`**, **2 in `Team/`**, plus
+    `Client_Adyen`, `Client_Compass`, `Client_Pcmaticb2b`, `Client_Quad`.
+  - **PROVEN broken, not theoretical:** `Client/2026-07-16c - AddressValidateScriptAcl.sql`
+    silently no-ops — Core script 28 (`addresses/validate`) has **zero** `AclRecordScripts` rows
+    in `Client_Rate`.
+  - **The root cause is not only the production tenant split.** A literal `Core.<Table>` does
+    **not** resolve to the 2.0 core on a developer machine either: **locally the 2.0 core is
+    `Core_2`, while `Core` is the *1.0* database**, which has no `RecordScripts` and no
+    `RecordFields` tables. So the statement fails **locally too** — `SET @var` stays NULL and the
+    `NOT EXISTS`-guarded INSERT silently inserts nothing. **Both environments break, by different
+    mechanisms.** This makes "it worked locally" impossible as a defense.
+  - **The fix is a literals swap, not a schema change.** Follow the prod-safe pattern already
+    documented at `Client/2026-06-23b - ItemTranslationsAcl.sql` (jcardinal): hardcode Core ids as
+    **literals**, resolve only client-local ids by name. And for a **client-specific scripted
+    API**, moving the registration to client-side `CustomRecordScripts` removes the cross-tenant
+    need **entirely** — see
+    [Record Scripts → client-side CustomRecordScripts](../../api2/features/record-scripts.md).
 - **A `VISIBILITY_RULE`/`ENABLED_RULE` override row can exist in the DB with the CORRECT `c_longValue`
   yet be silently ignored because its `attribute` coerced to `''`.** The `SurfaceOverrides.attribute`
   ENUM must be widened per client (`Client/2026-07-15 - SurfaceOverridesAttributeRuleValues.sql`)
@@ -500,6 +521,17 @@ rule resumes.
   override is added). **Open follow-up.**
 
 ## Change history
+- 2026-07-31 — **Closed the "audit the cross-DB surface seeds" open item** (TRUE-80487): swept all
+  505 non-`HISTORIC` `.sql` files and found **24** cross-tenant references (13 in `Client/`,
+  including the `BLANK_CLIENT_DATABASE` new-client template; 3 in `Client_Rate/`; 2 in `Core/`
+  reaching into `Client.*`; 2 in `Team/`; plus Adyen/Compass/Pcmaticb2b/Quad). Confirmed one
+  **proven-broken** instance (`Client/2026-07-16c - AddressValidateScriptAcl.sql` → Core script 28
+  has zero `AclRecordScripts` in `Client_Rate`) and recorded the **second, previously unknown
+  failure mechanism**: locally `Core` is the **1.0** database (the 2.0 core is `Core_2`), so a
+  literal `Core.<Table>` fails in local dev too — both environments break, by different causes.
+  Noted the remediation is cheaper than this doc assumed (hardcode Core ids as literals per
+  `Client/2026-06-23b`, or move a client-scoped scripted API to client-side `CustomRecordScripts`),
+  not a schema change. (mhammontree)
 - 2026-07-23 — Repointed the Order Details **"PO Number"** detail field (all clients, Core seed).
   `Core/2026-07-23a - PoNumberDetailFieldValueKey.sql` updates the `SurfaceElements` row (uuid
   `d45c51d8-8211-11f1-bfa7-a30f63c3a801`, label `salesOrder.field.poNumber`) `config` from

package/knowledge/INDEX.md

@@ -18,7 +18,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 40 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 42 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 38 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 20 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

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, dbchanges2/Client_Rate/2026-07-24a - AddressIdFieldPermission.sql |
 | [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 | > **STATUS (2026-07-27): beta-verified end-to-end; promoting to `_production`.** The final blocker > to a correct service-address pin turned out to be a **front | _underscore/Model/Rate/Entitlement.php, _underscore/Model/Client/Entitlement.php, _underscore/Model/Client/Address.php, toga2-view/src/pages/CheckOut/api/checkoutApi.ts, 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 Whole Home Warranty Per-Address Purchase Guard](features/whole-home-warranty-purchase-guard.md) | 2.0 | > # ⚠ STATUS (2026-07-31, TRUE-80487) — THE GUARD HAD NEVER EXECUTED, IN ANY ENVIRONMENT > > Everything below the next section described a guard that **never ra | _underscore/Model/Rate/Entitlement.php, _underscore/Model/Client/Entitlement.php, _underscore/Model/Client/Address.php, _underscore/Component/Library/Carriers/Usps/Usps.php, toga2-view/src/pages/CheckOut/api/checkoutApi.ts, toga2-view/src/pages/CheckOut/viewModel/useCheckoutPageViewModel.ts, toga2-view/src/pages/ZipValidation/api/zipValidation.ts, dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql, dbchanges2/Core/2026-07-22a - EntitlementServiceAddressIdField.sql, dbchanges2/Client_Rate/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql, dbchanges2/Client_Rate/2026-07-31a - WarrantyAvailabilityCustomRecordScript.sql, test/@Mark/Rate/verify_wholehome_per_address_guard.php, test/@Mark/Rate/verify_wh_gate_and_unit_dedup.php |
 | [Rate](profile.md) | 2.0 | Rate is a mortgage/lending client. |  |

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

@@ -6,24 +6,45 @@ project: _Underscore
 client: rate
 type: client-feature
 status: active
-updated: 2026-07-27
+updated: 2026-07-31
 owners: [mhammontree, tcox]
 files:
   - _underscore/Model/Rate/Entitlement.php
   - _underscore/Model/Client/Entitlement.php
   - _underscore/Model/Client/Address.php
+  - _underscore/Component/Library/Carriers/Usps/Usps.php
   - toga2-view/src/pages/CheckOut/api/checkoutApi.ts
+  - toga2-view/src/pages/CheckOut/viewModel/useCheckoutPageViewModel.ts
+  - toga2-view/src/pages/ZipValidation/api/zipValidation.ts
   - dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql
   - dbchanges2/Core/2026-07-22a - EntitlementServiceAddressIdField.sql
   - dbchanges2/Client_Rate/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql
+  - dbchanges2/Client_Rate/2026-07-31a - WarrantyAvailabilityCustomRecordScript.sql
   - test/@Mark/Rate/verify_wholehome_per_address_guard.php
+  - test/@Mark/Rate/verify_wh_gate_and_unit_dedup.php
 related:
   - clients/rate/profile.md
   - clients/rate/features/aig-contract-creation.md
   - ../../../2.0/apps/_underscore/features/address-validation.md
+  - ../../../2.0/apps/_underscore/features/usps-dpv-deliverability.md
+  - ../../../2.0/apps/_underscore/features/address-uniqueness-normalization.md
+  - ../../../2.0/apps/api2/features/record-scripts.md
 ---
 
-> **STATUS (2026-07-27): beta-verified end-to-end; promoting to `_production`.** The final blocker
+> # ⚠ STATUS (2026-07-31, TRUE-80487) — THE GUARD HAD NEVER EXECUTED, IN ANY ENVIRONMENT
+>
+> Everything below the next section described a guard that **never ran**. `isWholeHomeWarranty()`
+> read `$payload->saleItem->title`, but the real `toga2-view` checkout payload sends
+> `{"saleItem":{"uuid":"…"}}` with **no title** — so `stripos('')` was always false and `prePost`
+> returned **before** the guard on **every** purchase. **The guard's rejection message appears in
+> NO log, in ANY environment, ever.** Live proof: dev-sandbox held **3 active WH entitlements at
+> one address** (ET100057 / ET100067 / ET100073), two of them created **2026-07-27** — the day the
+> feature was marked "beta-verified". Three latent defects, the DPV enforcement, unit-level
+> address normalization, and a server-side availability endpoint all landed on TRUE-80487; read
+> **[What TRUE-80487 changed](#what-true-80487-changed-2026-07-31)** first, then the historical
+> detail below.
+>
+> **STATUS (2026-07-27, historical): beta-verified end-to-end; promoting to `_production`.** The final blocker
 > to a correct service-address pin turned out to be a **front-end request-`depth` bug**: Rate's
 > checkout was sending `{depth:-1}` on `POST /entitlements`, so V2 built a **shallow** payload
 > (`meta.calcDepth 1`) and `postPost` never received the nested
@@ -45,8 +66,9 @@ A customer may hold **one active Whole Home Warranty (WH) per validated address,
 Entitlements route via a `prePost` interceptor on `_Model_Rate_Entitlement`
 (`_underscore/Model/Rate/Entitlement.php`, Core.Records recordId **191**, registered PRE/POST).
 
-For **WH purchases only** (WH is identified by the sale-item title containing `"warranty"`,
-consistent with `resolvePurchaseProduct`), the guard:
+For **WH purchases only** — WH is identified by **resolving `saleItem.uuid` → `Items`** and
+matching on the **same authority the DB dedup uses** (title keyword **OR** `WH_SALE_ITEM_ID`);
+see [the identification defect](#what-true-80487-changed-2026-07-31) — the guard:
 
 1. **Requires a service address** from `$payload->contact->primaryContactAddress->address`.
 2. **Hard-blocks** the purchase if
@@ -65,6 +87,102 @@ confirmation-email flow.
 
 Ticket: TRUE-79533. Business rule owner: PM Paulina.
 
+## What TRUE-80487 changed (2026-07-31)
+
+### 1. The guard never fired — payload-shape mismatch on the WH test (FIXED)
+
+`isWholeHomeWarranty()` read **`$payload->saleItem->title`**. The real checkout payload is
+**`{"saleItem":{"uuid":"…"}}`** — **no `title`** — so the test was always false and `prePost`
+returned before the guard **in every environment since the feature shipped**.
+
+Now the guard **resolves `saleItem.uuid` → `Items`** and matches on the **same authority the DB
+dedup uses**: title keyword **OR** `WH_SALE_ITEM_ID`. It **deliberately does NOT fall back to
+`$payload->name`** — that is freeform client text the dedup never consults, so matching on it
+would make the guard and the dedup disagree.
+
+### 2. Second latent defect in the same path — `state.code` vs `state.uuid` (FIXED)
+
+The guard read `$address->state->code`, but the payload sends **`state.uuid`**. **Fixing #1
+alone would have thrown *"A valid service address is required"* on every valid purchase.**
+Added `resolveStateCode()` (prefers `code`, falls back to resolving the `uuid`).
+
+Also: the canonical write-back now **only overwrites `state->code` when the payload ALREADY
+carried that key**. Adding a `code` key to a uuid-only nested object is an **`EV-8` risk that
+rejects the whole POST.**
+
+### 3. Address comparison is now unit-level and ZIP5-level
+
+See [address-uniqueness-normalization](../../../2.0/apps/_underscore/features/address-uniqueness-normalization.md):
+`normalizeUnitIdentifier()` collapses `Suite 500` / `STE 500` / `#500` / `Apt 500` / `500` to
+`500` (an **empty** unit means the whole building and conflicts with **any** unit at that street
+address, in both directions), and `comparableZip()` compares the first 5 digits because USPS
+returns **ZIP+4** (`60503-7832`) while every legacy `Addresses` row holds 5 digits — an exact
+comparison had been missing **every legacy row**. SQL narrows on
+`line1 + city + ZIP5 + state`; the unit comparison runs in **PHP** over up to
+`DEDUP_CANDIDATE_LIMIT = 500` candidates (with an `error_log` canary).
+
+### 4. USPS DPV is now enforced — this is what implements the coverage rule
+
+See [usps-dpv-deliverability](../../../2.0/apps/_underscore/features/usps-dpv-deliverability.md).
+The waterfall was **discarding** DPV, and USPS returns **HTTP 200 with a populated address even
+when the unit is missing or invented** (it echoes `UNIT 200` back verbatim), so success alone was
+insufficient. Mapping: **`Y`** proceed / **`D`** reject *unit required* / **`S`** reject *unit not
+verified* / **`N`** reject / **unknown proceeds** (FedEx/UPS report no DPV; failing closed would
+block every purchase during a USPS outage, and the dedup still prevents duplicates).
+
+**This is what implements the business rule the developer specified: coverage is per UNIT when
+the building is subdivided, and per BUILDING when it is not.**
+
+### 5. `evaluateWholeHomeAddress()` is the SINGLE authority, exposed as an API
+
+One method performs: **completeness → carrier validation → DPV verdict → canonical adoption →
+global duplicate check**. `prePost()` **throws** on it; the new **`warrantyAvailability`**
+scripted API returns **the same verdict as data**. They cannot drift, because it is one method.
+
+Machine-readable reasons: `UNAVAILABLE_INCOMPLETE_ADDRESS`, `UNAVAILABLE_ADDRESS_UNVERIFIED`,
+`UNAVAILABLE_UNIT_REQUIRED`, `UNAVAILABLE_UNIT_INVALID`, `UNAVAILABLE_DUPLICATE_WARRANTY`, plus
+the canonical address.
+
+**Why it had to move server-side.** The availability check previously ran in the React app
+against **`useActiveServices(borrowerId)`** — a query scoped to the **logged-in borrower** — and
+could only see a warranty whose `serviceAddressId` had been **pinned**. **A warranty is per
+DWELLING, not per customer**, so it reported "eligible" whenever the existing warranty belonged
+to **someone else** or was **unpinned**; the customer then **paid through PayPal** and only then
+hit the server guard. Widening the FE query is **not** an option (cross-borrower data leak), so
+the question must be answered server-side. The response is a **boolean + generic reason**,
+leaking nothing about who holds an existing warranty. `toga2-view`'s local dedup in
+`pages/ZipValidation/*` was **DELETED, not patched**, and the page **fails CLOSED** if the call
+errors.
+
+### 6. Registration: a client-side `CustomRecordScript` (reusable pattern)
+
+`dbchanges2/Client_Rate/2026-07-31a - WarrantyAvailabilityCustomRecordScript.sql` registers the
+endpoint in the **client** database, **not** `Core.RecordScripts` — see
+[Record Scripts → client-side CustomRecordScripts](../../../2.0/apps/api2/features/record-scripts.md)
+for the full rationale (both tables are `DB_CLIENT`, so the grant resolves the script id from a
+hardcoded uuid in **one** database; a `Core` registration would force an impossible cross-tenant
+read). `recordId` is the literal **191**. Granted to **`Base` only, resolved by name** (role ids
+differ per client) and **never `Public`** — the endpoint reveals whether a warranty exists at an
+arbitrary address, so unauthenticated probing must be prevented. Verified by applying it twice to
+two environments: exactly one script row + one grant row.
+
+**Read the response at `data.entitlements["warranty-availability"]`** — the route verbatim, not
+the camelCase `phpMethod`. Reading `data.entitlements.warrantyAvailability` yields `undefined`
+and (correctly) fails closed; this cost a debug cycle in beta.
+(`toga2-view/src/pages/ZipValidation/api/zipValidation.ts`)
+
+### 7. Why the "works in beta, fails in production" report was FALSE
+
+Same code, same migrations, **byte-identical `ApiPayloadInterceptors` rows** in both environments
+(verified). The backend guard had **never run anywhere**. Beta only *appeared* correct because
+the **frontend** check happened to work there: every WH entitlement in beta belongs to a
+**single contact (`contactId 8`)** and all of its data was created **after** the pin shipped —
+satisfying both of the FE check's hidden preconditions (**same borrower**, **already pinned**).
+Production satisfied **neither**.
+
+> **Verification lesson (general):** *beta passing proves nothing if the dataset cannot exercise
+> the failing path.* Test as a **different borrower** and against **legacy / unpinned** data.
+
 ## Business rules (decided this session — Mark / Paulina)
 
 - **Invalid address → HARD BLOCK.** An address that fails carrier validation blocks the
@@ -72,8 +190,18 @@ Ticket: TRUE-79533. Business rule owner: PM Paulina.
 - **Uniqueness is GLOBAL per address**, not per-borrower — a second active WH on the same
   physical address is rejected regardless of which borrower buys it.
 - **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.
+  2A / 2B / 2C = three separate WHs. Uniqueness keys on the **normalized unit identifier** of
+  line2 (see [#3 above](#3-address-comparison-is-now-unit-level-and-zip5-level)) — designators are
+  discarded, and an **empty** unit means the whole building and conflicts with every unit.
+- **Coverage is per UNIT when the building is subdivided, per BUILDING when it is not** — and the
+  only signal that distinguishes those cases is **USPS DPV** (`D` = secondary unit required). See
+  [#4 above](#4-usps-dpv-is-now-enforced--this-is-what-implements-the-coverage-rule).
+- **`dateEnd` stays OUT of the dedup predicate (DECIDED 2026-07-31).** The active test is
+  `Subscriptions.isActive = 1 AND dateCancelled IS NULL`. Adding `dateEnd` would let **real**
+  duplicates through whenever a renewal has not rolled `dateEnd` forward — and renewals are not
+  advancing it: **production entitlement 40 (ET100014, Kimberly Stearns) has `dateEnd`
+  2026-06-01 yet was charged 2026-07-01.** That is a **separate defect worth its own ticket**;
+  `dateEnd` is currently unreliable as an indicator of anything.
 - **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
@@ -223,15 +351,66 @@ endpoint mechanics.
 
 A self-contained backend verification script lives at
 `test/@Mark/Rate/verify_wholehome_per_address_guard.php` (run via PHP CLI with `ENVIRONMENT`
-set, pinned to the real migrated **`Client_Rate`** schema — see the
-[2.0 backend-testing standard](../../../2.0/standards/backend-testing.md)). It applies
+set, pinned to the real migrated **`Client_Rate`** schema — there is no PHPUnit here, so
+backend verification is a standalone CLI script pinned to a real client database). It applies
 `c_serviceAddressId` idempotently, seeds a token-tagged scratch WH graph (2 addresses / 2 items /
 2 active subscriptions / 2 entitlements), then exercises the pure helpers, the dedup matrix (via
 reflection on the private methods), and the `prePost` branches, cleaning up in a `finally`. The
 live carrier waterfall is opt-in via `RUN_LIVE=1` (defaults off). Verified **18/18 pass**.
 
+> **⚠ That script passes 18/18 against a payload shape production NEVER SENDS** (`saleItem.title`
+> present, `state.code` present). **That is precisely why all three defects survived review.**
+> The replacement — **`test/@Mark/Rate/verify_wh_gate_and_unit_dedup.php` (77 assertions, all
+> passing)** — asserts against the **real uuid-only `saleItem` / `state` payload shape**, and its
+> `RUN_LIVE=1` section asserts the four live USPS DPV verdicts and that `prePost` **throws** for
+> `D` and `S`. **Verification scripts must use the real payload shape.**
+
+## Production + beta data cleanup (2026-07-31, done by the developer, query-verified)
+
+**Production** — three active WH warranties are now pinned and validated: **43 (ET100017) →
+address 9 Naperville**, **40 (ET100014) → address 6 Nashua**, **38 (ET100012) → address 4
+Wailuku**. Subscription **22 (ET100015, Daniel Moran)** closed out (`isActive = 0`,
+`dateCancelled` 2026-06-03). Address **7** city corrected from `"60657"` to `"Chicago"`. The
+**both-or-neither invariant** (`Entitlements.serviceAddressId` set ⟺ `Addresses.isValidated = 1`)
+holds on all **nine** rows.
+
+**Beta** — 23 subscriptions deactivated, leaving **0 active unpinned WH entitlements**.
+Previously **22 unpinned entitlements all belonged to `contactId 8`** and collapsed onto **ONE**
+address (`1864 HIGH GROVE LN STE 500`) through the `COALESCE(serviceAddressId, contact primary
+address)` fallback — which is what made beta's data look coherent.
+
+> **Near-miss worth remembering:** beta entitlements **100 / 105 / 106** were initially
+> misidentified as duplicates from a query that selected only `line1 + zip`. They are in fact
+> **DISTINCT units** (`STE 1900` / `# 4` / `STE 500`) and must **NOT** be deleted.
+> **Always fetch `line2` before judging address duplication.**
+
 ## Gotchas / known issues
 
+- **Apartment / property-type eligibility is CLIENT-SIDE ONLY and bypassable.** The property
+  questionnaire's `propertyType` lives in **router state / `sessionStorage`**
+  (`toga2-view/src/pages/CheckOut/viewModel/useCheckoutPageViewModel.ts`) and is **never sent to
+  the API** — the purchase payload carries no `propertyType` / `isEligible`. `prePost` requires
+  `line1`/`city`/`state`/`zip` but **not `line2`**, and the `requireUnitNumber` bounce-back is
+  **frontend navigation state only**. So an apartment building could be insured with **no unit at
+  single-dwelling pricing**. Live evidence: beta **ET100073** carries `line2` `"STE 500"` on a
+  **single-family** home. The **DPV `D`/`S` enforcement closes this server-side.** Note that
+  carriers cannot supply dwelling type at all (UPS/FedEx classification is only Residential vs
+  Commercial, and an apartment building is *Residential*) — true dwelling type needs property
+  data (assessor/parcel or a Melissa/Smarty-class vendor), a **procurement decision, not a code
+  one**.
+- **⚠ CORRECTION to the 2026-07-30 session doc.**
+  `knowledge/sessions/2026-07-30-TRUE-80487-Debug-Fix-Rate-WH-Warranty-mhammontree.md` records
+  *"cross-cluster `Core.*` refs from `Client*/` folders fail in prod — DISPROVEN … the ACL grants
+  landed correctly."* **That conclusion is WRONG.** The grants **exist** in production but
+  **cannot have been created by those migrations** — `Client/2026-07-16c -
+  AddressValidateScriptAcl.sql` silently no-ops, and Core script 28 (`addresses/validate`) has
+  **zero** `AclRecordScripts` rows in `Client_Rate`. Do not trust that line. See
+  [address-validation](../../../2.0/apps/_underscore/features/address-validation.md) and the
+  [dbchanges2 surface-layer audit](../../../2.0/apps/dbchanges2/features/surface-layer-schema.md).
+- **Renewals are not advancing `Subscriptions.dateEnd`** (production entitlement 40 charged a
+  month past its `dateEnd`). Separate defect, separate ticket — and the reason `dateEnd` is
+  excluded from the dedup predicate.
+
 - **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
@@ -350,6 +529,33 @@ live carrier waterfall is opt-in via `RUN_LIVE=1` (defaults off). Verified **18/
   block) — check `isValidated` to see whether the pin fired. (General 2.0 framework lesson.)
 
 ## Change history
+- 2026-07-31 — **THE GUARD HAD NEVER EXECUTED IN ANY ENVIRONMENT** (TRUE-80487, follow-up to the
+  already-deployed TRUE-79533). `isWholeHomeWarranty()` tested `$payload->saleItem->title` but the
+  real checkout payload sends `{"saleItem":{"uuid"}}` with no title, so `prePost` returned before
+  the guard on every purchase — its rejection message appears in **no log in any environment**
+  (proof: dev-sandbox held 3 active WH entitlements at one address, two created on the very day
+  the feature was called "beta-verified"). Fixed by resolving `saleItem.uuid → Items` and matching
+  on the same authority as the DB dedup (title keyword OR `WH_SALE_ITEM_ID`; deliberately **not**
+  `$payload->name`). Fixed a **second latent defect** in the same path — the guard read
+  `$address->state->code` while the payload sends `state.uuid`, so fixing the first alone would
+  have thrown "A valid service address is required" on every valid purchase (added
+  `resolveStateCode()`; the canonical write-back now only overwrites `state->code` when the payload
+  already carried that key, since adding it to a uuid-only node is an `EV-8` risk). Built
+  **unit-level + ZIP5 address comparison**, enforced **USPS DPV** (`Y`/`D`/`S`/`N`, unknown
+  proceeds) as the per-unit-vs-per-building signal, consolidated everything into the single
+  authority **`evaluateWholeHomeAddress()`**, and exposed it as the **`warrantyAvailability`**
+  scripted API (registered as a client-side `CustomRecordScript`, `Base`-only, never `Public`) so
+  the FE no longer answers a per-dwelling question with a per-borrower query — the old check
+  reported "eligible" whenever the existing warranty belonged to another borrower or was unpinned,
+  and the customer paid through PayPal before hitting the server guard. Recorded that the
+  "works in beta, fails in prod" report was **false** (identical code/migrations; beta only looked
+  right because all its WH data belonged to one already-pinned contact), that apartment eligibility
+  is **client-side only and bypassable**, that `dateEnd` stays out of the dedup (renewals are not
+  advancing it — separate defect), the production/beta data cleanup, and the **correction to the
+  2026-07-30 session doc's "cross-cluster refs DISPROVEN" claim**. New verification script
+  `test/@Mark/Rate/verify_wh_gate_and_unit_dedup.php` (77 assertions) asserts the **real** payload
+  shape — the old 18/18 script passed against a shape production never sends, which is why all
+  three defects survived review. (mhammontree)
 - 2026-07-27 — **Shipped working on beta end-to-end; status draft→active** (TRUE-79533). Found and
   fixed the **final** pin failure: the FE was POSTing `{depth:-1}` on `POST /entitlements`, building a
   shallow V2 payload (`calcDepth 1`) that **starved `postPost`** of the nested

package/knowledge/clients/rate/profile.md

@@ -9,11 +9,12 @@ apps:
   - worker
   - worker2
   - dbchanges2
+  - test
 project: SAML SSO Gateway
 client: rate
 type: profile
 status: active
-updated: 2026-07-23
+updated: 2026-07-31
 owners: ["rgirish", "bala", "mhammontree", "tcox"]
 files: []
 related:

package/knowledge/sessions/2026-07-30-TRUE-80487-Debug-Fix-Rate-WH-Warranty-mhammontree.md

@@ -37,7 +37,7 @@ updated: 2026-07-30
 - **"TRUE-79251 merge damage deleted the WH helper methods."** DISPROVEN. `git diff origin/_beta -- Model/Rate/Entitlement.php` → zero diff. `PASSTHROUGH_KEY_FULFILLMENT_PREFERENCE` (line 32) and all three private helpers (`normalizedField` 107, `isWholeHomeWarranty` 116, `hasActiveWarrantyAtAddress` 137) present.
 - **"`_underscore` prod wasn't redeployed past the uuid-clobber fix `9c2e4b1c`."** DISPROVEN by the same zero diff + PR #661 merged.
 - **"`toga2-view` prod still sends `{depth:-1}` and starves `postPost`."** DISPROVEN. `genericApi.ts:54,68` only append `?depth=-1` when `returnPayloadDepth` is explicitly set; no checkout override. Diff vs `_beta` touches only GetSupport files.
-- **"Cross-cluster `Core.RecordFields` references from `Client*/` migration folders fail in prod."** DISPROVEN for this case. Despite prod splitting `prod-core` / `prod-client` / `prod-logs` / `prod-archive` onto separate clusters, the ACL grants landed correctly. ~20 long-standing ACL migrations use this same pattern. (Note: the `dbchanges2-cluster-isolation` hook was NOT found under `.claude/hooks/toga/` — separate follow-up, not this bug.)
+- **"Cross-cluster `Core.RecordFields` references from `Client*/` migration folders fail in prod."** **⚠ CORRECTED 2026-07-31 — THIS CONCLUSION WAS WRONG.** The grants *exist* in production but **cannot have been created by those migrations**: `Client/2026-07-16c - AddressValidateScriptAcl.sql` silently no-ops and Core script 28 (`addresses/validate`) has **zero** `AclRecordScripts` rows in `Client_Rate`. A literal `Core.<Table>` also fails **locally**, where `Core` is the **1.0** database (2.0 core is `Core_2`). An audit found 24 such files. See `clients/rate/features/whole-home-warranty-purchase-guard.md` and `2.0/apps/dbchanges2/features/surface-layer-schema.md`. Original (incorrect) text follows: DISPROVEN for this case. Despite prod splitting `prod-core` / `prod-client` / `prod-logs` / `prod-archive` onto separate clusters, the ACL grants landed correctly. ~20 long-standing ACL migrations use this same pattern. (Note: the `dbchanges2-cluster-isolation` hook was NOT found under `.claude/hooks/toga/` — separate follow-up, not this bug.)
 - **"The interceptor row is missing, inactive, or duplicated in prod."** DISPROVEN — prod rows are identical to dev-sandbox, same ids and uuids.
 - **"`POST /v2/entitlement-sales-orders` is the prod purchase path (record 257, no interceptor)."** DISPROVEN. It is only a bridge link: payload is `{"entitlement":{"uuid"},"salesOrder":{"uuid"}}`. It creates no entitlement and fires no interceptor.
 - **"Production simply hasn't processed a purchase since deploy, so there's nothing to debug."** TRUE as a fact (last `POST /v2/entitlements` in prod = 2026-07-10, two × 400 `EV-8`; newest `Entitlements` row 2026-06-15) but WRONG as a conclusion — the developer then reproduced the failure live through the UI. Do not stop at this observation.

package/package.json

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