toga-ai 1.0.488 → 1.0.490

package/.claude/settings.json

@@ -41,6 +41,26 @@
             "timeout": 3000
           }
         ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \".claude/hooks/toga/dbchanges2-cluster-isolation.js\"",
+            "timeout": 3000
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \".claude/hooks/toga/dbchanges2-record-ids.js\"",
+            "timeout": 3000
+          }
+        ]
       }
     ],
     "PostToolUse": [

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/architecture.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: architecture
 status: active
-updated: 2026-07-29
+updated: 2026-07-31
 owners: [jcardinal, mhammontree, bala, ajean]
 files:
   - Core/
@@ -43,6 +43,9 @@ UI config) — **not just schema**; a schema-only blank produces non-functional
 `Archive_*`, `Logs*`, and `Cache` are on **separate production clusters**, so any
 `OtherDatabase.Table` reference is unrunnable in production even though it works locally
 (see *Database isolation* below; enforced by the `dbchanges2-cluster-isolation` hook).
+**`Core.Records` and `Core.RecordFields` are the only two tables platform-wide with
+team-maintained `id`s** — ask the developer for the next value before inserting (never
+`AUTO_INCREMENT`), and hardcode those `id`s wherever they are referenced, foreign keys included.
 
 ## File naming convention (the execution contract)
 
@@ -189,6 +192,61 @@ literals are stripped first, and table **aliases** (`rf.id`, `sibling.roleId`) a
 > is **not** subject to it. If the hook ever misfires on legitimate SQL, `DBCHANGES2_ISOLATION_DISABLED=1`
 > is an escape hatch **for false positives only** — never to land a cross-database query.
 
+## `Core.Records` / `Core.RecordFields` — the only hardcoded `id`s on the platform
+
+These **two tables, and only these two**, have **team-maintained primary keys**. Their `id`
+values are treated as **stable, platform-wide constants**: the team tracks the next available
+value **in the developer chat**, and every environment carries the same `id` for the same record
+/ field. Nothing else on the platform may have a hardcoded `id`.
+
+This is what makes the *Database isolation* rule above practical — it is the reason a
+`Client_<Tenant>` migration never needs to read `Core` to find a `recordFieldId`.
+
+### Inserting into them — ASK FIRST, never rely on AUTO_INCREMENT
+
+**When a change inserts into `Core.Records` or `Core.RecordFields`, stop and ask the developer
+for the next `id` value(s)**, then write them as explicit literals:
+
+```sql
+# Core/2026-07-31a - Add entitlements serviceAddressId field.sql
+# id values 4187, 4188 assigned by the team (developer chat) — do NOT let AUTO_INCREMENT pick.
+INSERT INTO RecordFields (id, uuid, recordId, `field`)
+VALUES (4188, '<pre-generated v4 uuid>', 219, 'serviceAddressId');
+```
+
+**Never omit `id` and let MySQL's `AUTO_INCREMENT` assign it.** The column's `AUTO_INCREMENT`
+definition still exists, but it is **not the source of truth** — allowing it to assign a value
+lets environments drift apart, and every hardcoded reference to that `id` (in other databases,
+in PHP, in other migrations) then points at the wrong row or nothing at all. There is no way to
+detect this from inside the migration; it simply produces silently wrong ACL/field wiring.
+
+Because the `id`s must be reserved by a human, **this cannot be guessed or derived** — asking is
+mandatory, not a courtesy. Record the assigned values in a comment at the top of the file so the
+next reader knows they were allocated, not invented.
+
+### Referencing them — hardcode the `id`, including foreign keys
+
+Anywhere a query references one of these rows — **and anywhere a foreign key points at them**
+(`recordId`, `recordFieldId`, and their equivalents) — **hardcode the numeric `id`**. Do not look
+it up:
+
+```sql
+# Client_Compass/2026-07-31a - Grant serviceAddress field write.sql
+# recordFieldId 4188 = Core.RecordFields entitlements.serviceAddressId (team-assigned constant)
+INSERT INTO AclFieldPermissions (uuid, recordFieldId, roleId, isWritable)
+VALUES ('<pre-generated v4 uuid>', 4188, 3, 1);
+```
+
+This applies equally to SQL embedded in PHP in `worker2` / `api2` / `_underscore` — a hardcoded
+`recordFieldId` is correct and preferred there too.
+
+> **Always comment what the number is.** A bare `4188` is unreadable and unverifiable six months
+> later. Name the record/field it refers to, as above.
+
+Note that the `uuid` on these rows is **also** stable and environment-consistent, so
+`WHERE uuid = '<literal>'` is a valid alternative when a readable key is preferred — but the
+`id` is the team-maintained one, and it is what foreign keys store.
+
 ## `_modules` — reusable, opt-in change-sets
 
 Some change-sets aren't applied to every client — only to clients that use a given **module**
@@ -295,6 +353,12 @@ its own header.)
    foreign ids with a hardcoded v4 UUID literal or an in-database slug/natural key, or split the
    work into one file per database folder. See *Database isolation* above — enforced by the
    `dbchanges2-cluster-isolation` hook.
+9. **Inserting into `Core.Records` or `Core.RecordFields`? ASK the developer for the next `id`.**
+   These are the **only two tables on the platform with team-maintained primary keys** (tracked in
+   the developer chat). Write the assigned `id` as an explicit literal — **never** let
+   `AUTO_INCREMENT` assign it. Conversely, **always hardcode** these `id`s where they are
+   referenced, including in foreign keys (`recordId`, `recordFieldId`) from other databases. See
+   *`Core.Records` / `Core.RecordFields`* above.
 
 ## Bulk data loads — batch, and stage large sets in a temp table
 
@@ -447,7 +511,16 @@ defined in `2.0/apps/_underscore/architecture.md`, and its change files create/a
 tables that `_Model_*` classes map to.
 
 ## Change history
-- 2026-07-29 — **Added *Database isolation — never query across databases* (HARD RULE) + rule #8.**
+- 2026-07-31 — **Added *`Core.Records` / `Core.RecordFields` — the only hardcoded `id`s on the
+  platform* + rule #9.** These two tables are the **only** ones platform-wide whose `id` is a
+  team-maintained constant: the next available value is tracked **in the developer chat**, so a
+  migration inserting into them must **ask the developer for the `id`** and write it as an explicit
+  literal — `AUTO_INCREMENT` must never assign it (silent per-environment drift breaks every
+  hardcoded reference). Conversely these `id`s **should** be hardcoded wherever referenced,
+  including foreign keys (`recordId`, `recordFieldId`) from client databases and in PHP query
+  strings. This is what makes *Database isolation* workable — no client migration needs to read
+  `Core` to resolve a `recordFieldId`. Enforced by the `dbchanges2-record-ids` hook. (jcardinal)
+- 2026-07-31 — **Added *Database isolation — never query across databases* (HARD RULE) + rule #8.**
   A `dbchanges2` `.sql` file may only reference tables in the one database its folder targets, and
   must reference them unqualified; fan-out folders (`Client/`, `Logs_Client/`, `_modules/`) permit
   no database qualifier at all. Rationale: in production `Core`, `Client_<Tenant>`,