toga-ai 1.0.283 → 1.0.285

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

@@ -4,7 +4,9 @@
 |-----|---------|-------|
 | [_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, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.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 |
 | [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 |
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
 | [Error Reporting — Issue/Event Aggregation (exceptionHandler)](features/error-reporting-issue-event.md) | `_underscore`'s global exception handler persists every uncaught exception into a two-table **Issue / Event** model in the **shared Core Logs DB** (`_underscore | _underscore/Error.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/Event.php, dbchanges2/Logs/2026-07-06 - Issue and Event tables.sql |

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: architecture
 status: active
-updated: 2026-07-02
+updated: 2026-07-07
 owners: ["jcardinal", "rgirish", "mhammontree"]
 files:
   - _underscore/_underscore.php
@@ -119,6 +119,16 @@ multi-tenant client-DB lookup from Core. `Query.php` wraps MySQLi with read/writ
 auto-routing and result helpers: `fetchRows()`, `fetchRow()`, `fetchOne()`,
 `fetchRowsAssocArray()`, `fetchKeyValuePairs()`, `fetchValues()`.
 
+`_Query` also supports a **writes-only async mode** (`isAsync` — 3rd constructor arg /
+`setIsAsync()`): a slow WRITE is dispatched to the Worker tier via `_Worker::runTask()`
+instead of running on the request connection, so a long write cannot hold a request-scoped
+connection open long enough to hit **"MySQL server has gone away."** See
+[features/async-query-execution.md](./features/async-query-execution.md). This rides on the
+**SQS-first** `_Worker::runTask()` enqueue path (below): `runTask()` no longer INSERTs the
+`WorkerJobs` row on the caller's connection — it sends `{uuid, action, parameters}` to the
+worker SQS queue and the worker tier creates/tracks the row on its own fresh connection at
+pickup (see the worker2 architecture doc's SQS-first decision).
+
 ### Physical infrastructure
 
 Each **environment** is one or more MySQL clusters. Every cluster has a single
@@ -338,3 +348,4 @@ multi-file UI components (`.php`/`.html`/`.css`/`.js`) invoked as `<_ComponentNa
 - 2026-06-25 — Added the Surface platform UI presentation/configuration layer (DB-driven UI config replacing `Page::meta()`, CTO-reviewed AGREE-WITH-ADJUSTMENTS) (jcardinal)
 - 2026-06-29 — Surface made the enforced (un-flagged) presentation path; reserved id blocks renumbered to Records 333–341 / RecordFields 2246–2433 (known seed-vs-provisioned drift). (jcardinal)
 - 2026-07-02 — Fixed framework-wide `FIELD_STORAGE` write-drop and folder-read bugs in `Model.php`; noted the remaining unconditional-refetch dirty-read follow-up. (mhammontree)
+- 2026-07-07 — Documented `_Query` writes-only async mode (`isAsync` → Worker `Infrastructure/Database/Query`) in the database-architecture section, linked `features/async-query-execution.md`, and noted the SQS-first `_Worker::runTask()` enqueue departure (caller does no MySQL; worker tier creates the row on pickup). (jcardinal)

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

@@ -0,0 +1,76 @@
+---
+title: "Address Validation (carrier waterfall + validateAddress scripted endpoint)"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-07-07
+owners: [mhammontree]
+files:
+  - _underscore/Model/Client/Address.php
+related:
+  - ../../api2/features/scripted-api-post-body-args.md
+  - ../../api2/architecture.md
+  - ../../../clients/rate/features/whole-home-warranty-purchase-guard.md
+---
+
+## Summary
+
+`_Model_Client_Address::validateAddress` verifies a US address against a **carrier
+waterfall (USPS → FedEx → UPS)** and returns a single canonical, carrier-normalized
+address. It is exposed to the frontend as the **global** scripted endpoint
+`GET /addresses/validateAddress`, and is also callable server-side by any model/interceptor
+that needs to validate + normalize an address before persisting it (e.g. the Rate
+Whole Home Warranty purchase guard).
+
+## Key files / entry points
+
+- `_Model_Client_Address::validateAddress(&$api, $address1, $address2, $city, $state, $zip)`
+  (`_underscore/Model/Client/Address.php`) — runs USPS, then FedEx, then UPS.
+  - **On success** (carriers agree) returns keys: `success:true`, `address1`, `address2`,
+    `city`, `state` (2-letter code), `zipCode`, `country`. UPS additionally supplies
+    `zip4`/`zip5`.
+  - **On failure** (all carriers fail) returns the **last (UPS) response** with
+    `success:false` (and an `error`).
+
+## The scripted endpoint is registered in the DB, not in source (parity gap)
+
+The `GET /addresses/validateAddress` endpoint the frontend calls is wired as a **global**
+scripted endpoint in **`Core.RecordScripts`** (id 17: `recordId` 13 = Addresses, method
+`GET`, route `validateAddress`, `phpMethod` `validateAddress`). Verified in production
+2026-07-07.
+
+- It is **not** in any client-level `CustomRecordScripts` (Rate's is empty), and it is
+  **not** present in `dbchanges2` source — the registration exists **only in the live DB**.
+  Treat this as a known source/DB parity gap: you will not find the endpoint by grepping
+  `dbchanges2`.
+- **Dispatch precedence:** the V2 engine checks `Core.RecordScripts` **before** a client's
+  `CustomRecordScripts`, so a global script wins for every client unless a client overrides it.
+- **Response path:** a scripted method's return value is placed at
+  `data.<record>.<route>` in the API envelope — so `validateAddress` (record = Addresses,
+  route = validateAddress) returns to **`data.addresses.validateAddress`**, which is exactly
+  what the frontend reads.
+
+## Client variations
+
+None — this is shared engine + framework behavior. The carrier credentials are resolved
+per the standard client carrier config.
+
+## Gotchas / known issues
+
+- **DB-only registration.** Because the `Core.RecordScripts` row is not in `dbchanges2`,
+  the endpoint's existence is invisible to source search and is not reproduced by replaying
+  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.
+
+## Change history
+
+- 2026-07-07 — Documented `_Model_Client_Address::validateAddress` (USPS→FedEx→UPS waterfall
+  + normalized success shape) and the global `GET /addresses/validateAddress`
+  (`Core.RecordScripts` id 17) endpoint, including the dispatch precedence, the
+  `data.<record>.<route>` response path, and the dbchanges2 source/DB parity gap
+  (registration lives only in the live DB). Prod-verified while building the Rate WH purchase
+  guard (TRUE-79533). (mhammontree)

package/knowledge/2.0/apps/_underscore/features/async-query-execution.md

@@ -0,0 +1,89 @@
+---
+title: Asynchronous Query Execution (writes-only, via Worker)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-07-07
+owners: ["jcardinal"]
+files:
+  - _underscore/Query.php
+  - worker2/Worker/Infrastructure/Database.php
+  - worker2/Worker/Team/Transcripts.php
+related:
+  - ../architecture.md
+  - ./per-client-database-connections.md
+---
+
+## Summary
+
+`_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 gone away"**.
+Instead of executing on the local connection, the query is dispatched as a Worker task
+(`Infrastructure/Database/Query`) that opens its own connection on the target DB, runs the
+write, and commits. It is **writes-only by design** — an async SELECT captures no result set
+and is a harmless no-op.
+
+## Key files / entry points
+
+- **`_underscore/Query.php`** — `_Query` gained an `isAsync` flag: constructor 3rd param
+  `bool $isAsync = false`, a `setIsAsync()` setter, and an `_isAsync` property. When async,
+  `execute()` resolves the target DB connection config and dispatches a Worker task instead of
+  running locally.
+- **`worker2/Worker/Infrastructure/Database.php`** — `_Worker_Infrastructure_Database::Query()`
+  is the worker-side action that runs the write on the target DB and commits.
+- **`worker2/Worker/Team/Transcripts.php`** — live example caller in `SyncKnowledgeBases()`
+  (lines ~911 / ~925).
+
+## How it works
+
+1. **Opt in.** Construct with the third arg true:
+   `new _Query($sql, _underscore::DB_TEAM, true);` (or call `setIsAsync(true)` before the
+   query is set).
+2. **Dispatch (in `execute()`).** When `_isAsync` is true, `execute()` does **not** run the
+   query locally. It resolves the target DB connection config — from `_Database::$_registers`
+   or the `_Config` `DATABASE` group (direct hostname, or `writehost`/`readhost` + `backuphost`
+   params) — and calls
+   `_Worker::runTask(action: 'Infrastructure/Database/Query', parameters: {hostname, database,
+   username, password, query})`.
+3. **Worker side.** `_Worker_Infrastructure_Database::Query()` calls `_Database::register(...)`
+   under the alias `'Query'`, runs `new _Query($query, 'Query')` to execute the write on the
+   worker's own connection, then commits with `_Database::transactionCommit('Query')`.
+4. **Writes only.** Async SELECT captures no result set (fire-and-forget) and is treated as a
+   harmless no-op — do not use async for reads.
+
+## Correctness gotchas (all fixed this session — do not regress)
+
+- **Constructor order (critical).** `setIsAsync()` must run **before** `setQuery()`, because
+  `setQuery()` executes non-SELECT queries immediately. With the original order (setQuery first)
+  every async WRITE ran synchronously and the async path was never taken. The constructor was
+  reordered to set the async flag first.
+- **Worker-side commit (critical).** `_Database::register()` with an alias auto-starts a lazy
+  transaction; the write flips autocommit off and is rolled back when the worker connection
+  closes unless explicitly committed. The worker action must call
+  `_Database::transactionCommit('Query')` after the write. This is the known _underscore
+  [lazy-transaction gotcha](../architecture.md) — the same trap that silently discarded Rate
+  SAML user INSERTs.
+- **Double-dispatch.** The async branch leaves `_results` null, and `execute()` is guarded by
+  `is_null(_results)`, so `__destruct()`/getters re-fire the job. Fixed by setting a sentinel
+  (`_results = true`) at the end of the async branch.
+- **Dangling local transaction.** The original async check ran **after** the
+  write-connection/transaction setup, so a dispatching async write opened a local writer
+  connection and started a local transaction it never committed. Fixed by moving the async
+  dispatch to the **top** of `execute()`, before any read/write connection or transaction setup.
+
+## Known open items
+
+- **SECURITY (open, developer aware).** DB username/password are currently sent in **plaintext**
+  through the Worker queue payload (SQS + `WorkerJobs` table). Being handled separately: the
+  worker should resolve credentials from config by database name rather than receiving them in
+  the payload. Do not build on the plaintext-credential path.
+
+## Change history
+
+- 2026-07-07 — Built writes-only async query execution (`_Query` `isAsync` → Worker
+  `Infrastructure/Database/Query` action); fixed four correctness bugs found in review
+  (constructor order, worker-side commit, double-dispatch sentinel, dangling local
+  transaction). Credential-in-payload security item left open. (jcardinal)

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: architecture
 status: active
-updated: 2026-06-08
+updated: 2026-07-07
 owners: [jcardinal]
 files:
   - worker2/Controller/Index.php
@@ -15,6 +15,7 @@ files:
   - _underscore/Worker.php
 related:
   - ./features/creating-worker-actions.md
+  - ../_underscore/features/async-query-execution.md
 ---
 
 ## Summary
@@ -92,8 +93,29 @@ New path (`{workerJobId}` present):
 5. Call `initialize()` if present, then the action with spread parameters.
 6. **Check-out:** `UPDATE dtCompleted, executionTime, isSuccess, failureReason`. Return 200.
 
-Legacy path (`action` present, no `workerJobId`): used by `_Worker::runTask()` debug mode
-only; runs directly with no `WorkerJobs` tracking.
+Direct-payload path (`action` present, no `workerJobId`): formerly the debug-only "legacy"
+path (untracked, could return HTTP 500). As of 2026-07-07 it is a **first-class tracked
+path** — it is how the SQS-first `_Worker::runTask()` (below) delivers production jobs. The
+message carries `{uuid, action, parameters}`; the worker creates and tracks the `WorkerJobs`
+row on its own fresh connection and **always returns HTTP 200** (no DLQ + 3600s visibility
+timeout means any 500 = poison-message storm):
+
+1. **Dedupe guard.** SELECT `WorkerJobs` by `uuid`. Skip (200) **only if `isSuccess IS NOT
+   NULL`** (already completed). A row that exists but is incomplete (prior crash / in-flight)
+   is **re-run**, not dropped — mirrors the `workerJobId` guard. (SQS is at-least-once.)
+2. **New job → INSERT** `(uuid, jobType='ACTION', action, parameters, dtQueued=NOW(),
+   dtStarted=NOW(), instanceId)`. A UNIQUE index on `WorkerJobs.uuid` (added in `dbchanges2`)
+   backstops the SELECT→INSERT TOCTOU race.
+3. **INSERT-failure disambiguation** is by **re-resolving the uuid**, not by parsing the
+   error code: if the row now exists it was a benign concurrent duplicate (skip 200);
+   otherwise the write genuinely failed — log CRITICAL + `\Sentry\captureException`, still
+   return 200.
+4. `dtQueued=NOW()` at insert (not NULL) so JobScheduler's `dtQueued IS NULL` recovery does
+   not re-queue these rows; the watchdog still covers them via `dtStarted`.
+
+> **Known follow-up (not done):** the ~100-line log-DB-registration + `initialize()` blocks
+> are duplicated between the `workerJobId` path and the direct-payload path — candidate for
+> extraction to shared private helpers.
 
 ## Action → class/method routing
 
@@ -103,9 +125,17 @@ file `Worker/Team/Github.php`.
 
 ## Programmatic invocation & manual retry
 
-- **`_Worker::runTask(action, parameters)`** (`_underscore/Worker.php`) — INSERT
-  `WorkerJobs` → **`transactionCommit(DB_CORE)` before SQS** → send `{workerJobId}`.
-  Debug mode posts synchronously with no tracking.
+- **`_Worker::runTask(action, parameters)`** (`_underscore/Worker.php`) — **SQS-first as of
+  2026-07-07:** the production branch does **no MySQL** (no INSERT, no commit). It generates a
+  client-side `uuid` and sends `{uuid, action, parameters}` to the worker SQS queue; the worker
+  tier creates+tracks the `WorkerJobs` row on pickup (see direct-payload path above). Payload is
+  capped at `_Worker::SQS_MAX_MESSAGE_BYTES = 262144` — `runTask()` **throws** if the JSON
+  exceeds the SQS 256KB limit (loud failure, not a silent drop); oversized params must be
+  offloaded to S3 by the caller. Debug branch unchanged (synchronous POST). **Why:** long-running
+  scripts hit "MySQL server has gone away" on the caller's stale Core connection during the old
+  INSERT; SQS sends do not depend on the DB connection, so row creation moved off the caller
+  entirely. This is the enqueue path used by `_Query` writes-only async mode. See the SQS-first
+  decision + trade-off under *Key design decisions*.
 - **`_Worker_Infrastructure_Worker::Retry($workerJobId)`** — resets the job fields,
   commits before SQS, sends `{workerJobId}` immediately. Sets `dtQueued=NOW()` (not NULL)
   so JobScheduler doesn't double-pick it.
@@ -118,17 +148,56 @@ file `Worker/Team/Github.php`.
 ## Critical transaction pattern
 
 **Any INSERT/UPDATE that must be visible to another connection before an SQS message is
-delivered must be immediately committed.** Three sites: `Retry()`, `_Worker::runTask()`,
-and the `Controller/Index.php` check-in. Reason: the caller's MySQL transaction is still
+delivered must be immediately committed.** Sites: `Retry()` and the `Controller/Index.php`
+check-in. (`_Worker::runTask()` no longer applies as of 2026-07-07 — it does no MySQL; the
+worker tier creates the row itself on pickup.) Reason: the caller's MySQL transaction is still
 open when SQS delivers; the worker reads in a separate connection and, if uncommitted, its
 SELECT returns nothing and the guard fires ("already processed or not found — skipping").
 
 ## Key design decisions
 
-MySQL-first (SQS on success) prevents lost jobs · always HTTP 200 (WorkerJobs tracks
-failures, SQS retry unwanted) · 3600s visibility timeout for hour-long jobs · no DLQ
-(developer-controlled `Retry()` preferred) · all fallback payloads to S3 (no size split) ·
-SQS failure → reset `dtQueued=NULL` (rescheduled next minute) · `maxExecutionTime` on
-CronJobs, env var for ACTION jobs · `/Webhook` appended enforces method-name convention ·
-API Gateway in front of Lambda (SCP blocks Function URLs) · `workerJobId` lookup keeps SQS
-messages tiny · commit before SQS avoids the delivery-before-commit race.
+MySQL-first for the **Lambda/webhook/cron ingestion paths** (SQS on success) prevents lost
+jobs · always HTTP 200 (WorkerJobs tracks failures, SQS retry unwanted) · 3600s visibility
+timeout for hour-long jobs · no DLQ (developer-controlled `Retry()` preferred) · all fallback
+payloads to S3 (no size split) · SQS failure → reset `dtQueued=NULL` (rescheduled next
+minute) · `maxExecutionTime` on CronJobs, env var for ACTION jobs · `/Webhook` appended
+enforces method-name convention · API Gateway in front of Lambda (SCP blocks Function URLs) ·
+`workerJobId` lookup keeps SQS messages tiny · commit before SQS avoids the
+delivery-before-commit race.
+
+### `_Worker::runTask()` is SQS-first, NOT MySQL-first (2026-07-07 — intentional departure)
+
+For **programmatic** enqueue via `_Worker::runTask()`, the MySQL-first rule was deliberately
+reversed. Long-running PHP scripts were hitting "MySQL server has gone away" on the caller's
+`WorkerJobs` INSERT because the caller's Core connection had gone **stale** (not because the
+server was dying). Approach chosen (**A — SQS-first**): the caller does no MySQL; it sends
+`{uuid, action, parameters}` to SQS and the worker tier creates+tracks the row on its own
+fresh connection at pickup.
+
+**Rejected alternative (CTO-recommended):** Approach C/D — reconnect-on-stale inside
+`_Database`, keeping the durable id-based (MySQL-first) pipeline. The CTO review advised
+**against** Approach A because the failure is a stale PHP connection rather than a dying
+server, and because promoting the debug-only untracked path risked poison-message storms and
+duplicate execution. The developer chose Approach A anyway, **accepting the durability
+trade-off**: a bare SQS-send failure loses the job, and jobs are not visible in `WorkerJobs`
+until worker pickup. The CTO review's known-danger mitigations were then implemented — uuid
+dedupe that re-runs incomplete rows, UNIQUE `uuid` index for the TOCTOU race, uuid
+re-resolution to disambiguate INSERT failures (CRITICAL log + Sentry on genuine failure),
+always-200, and a 256KB payload cap that throws. Record kept so a future reader understands
+the MySQL-first design was departed from **on purpose** here.
+
+**Gotchas from this change:**
+- `dtQueued` on these rows now reflects worker pickup/row-creation time, **not** true SQS
+  enqueue time — semantic drift for any queue-latency metric.
+- Debug/legacy messages without a `uuid` get a random one, so dedupe does not apply to them —
+  an HTTP-layer retry of a debug call could double-run.
+
+## Change history
+
+- 2026-06-08 — Initial worker2 architecture doc. (jcardinal)
+- 2026-07-07 — `_Worker::runTask()` moved to SQS-first (caller does no MySQL; worker tier
+  creates/tracks the row on pickup); the former debug-only direct-payload path in
+  `Controller/Index.php` promoted to a first-class tracked path with uuid dedupe, UNIQUE-index
+  TOCTOU backstop, uuid re-resolution on INSERT failure, and a 256KB payload cap. Documented as
+  an intentional departure from MySQL-first (CTO recommended against; trade-off accepted).
+  Related: `_underscore` `_Query` writes-only async mode. (jcardinal)

package/knowledge/INDEX.md

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 22 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 25 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 27 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 10 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,4 +8,5 @@
 | [Rate SAML SSO](features/saml-sso.md) | 2.0 | Rate uses Azure AD as its IdP (`login.rate.com`). | _underscore/Model/Rate/ClientAuthentication.php, saml/Controller/Index.php, toga2-view/src/hooks/useAuthenticationFlow.ts |
 | [Service Card Entitlement Display](features/service-card-entitlements.md) | 2.0 | Rate's home and services pages display one service card per purchased entitlement. | src/components/ServiceCard/ServiceCard.tsx, src/components/ServiceCard/index.ts, src/hooks/useBundleServices.ts, src/pages/Home/api/homeApi.ts, src/pages/Home/view/HomePage.tsx, src/pages/Home/viewModels/useHomePageViewModel.ts, src/pages/Services/view/ServicesPage.tsx, src/pages/Services/viewModels/useServicePageViewModel.ts |
 | [Rate Service-Purchase Confirmation Emails (Tech / Warranty)](features/service-purchase-emails.md) | 2.0 | When a Rate customer purchases a service, a confirmation email is sent. | _underscore/Model/Rate/Entitlement.php, worker2/Worker/Notification/EmailTemplate.php, dbchanges2/Client_Rate/2026-06-30a - Rate purchase email templates.sql |
+| [Rate Whole Home Warranty Per-Address Purchase Guard](features/whole-home-warranty-purchase-guard.md) | 2.0 | A customer may hold **one active Whole Home Warranty (WH) per validated address, globally** (across all borrowers). | _underscore/Model/Rate/Entitlement.php, _underscore/Model/Client/Address.php, dbchanges2/Client_Rate/2026-07-07a - WholeHomeWarrantyPerAddressGuard.sql |
 | [Rate](profile.md) | 2.0 | Rate is a mortgage/lending client. |  |

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

@@ -14,6 +14,7 @@ files:
   - worker2/Worker/Monitors/RateEntitlement.php
 related:
   - clients/rate/profile.md
+  - clients/rate/features/whole-home-warranty-purchase-guard.md
   - ../../../2.0/apps/worker2/features/monitoring-framework.md
 ---
 
@@ -35,6 +36,13 @@ This is a base-`_underscore` interceptor specific to Rate's product (it lives un
 `Model/Rate/`); documented here as a Rate client-feature because the behavior and its
 monitoring are Rate-scoped.
 
+**As of 2026-07-07 (TRUE-79533)** the same `postPost` also persists the validated **service
+address** (`Entitlements.c_serviceAddressId`, `Addresses.isValidated=1`) — that persistence is
+wrapped so it never blocks this AIG-contract flow or the confirmation email. For Whole Home
+Warranty purchases, a new `prePost` guard now also **carrier-normalizes the address onto the
+payload before save**, so the AIG contract is created with the canonical address. See the
+[Whole Home Warranty per-address purchase guard](whole-home-warranty-purchase-guard.md).
+
 ## How it works
 
 1. `postPost` runs after an entitlement is saved. It proceeds **only if** the payload has a
@@ -91,6 +99,10 @@ creation vs. cancellation. This is an accepted, documented limitation — not an
 
 ## Change history
 
+- 2026-07-07 — `postPost` now also persists the validated service address
+  (`Entitlements.c_serviceAddressId`, `Addresses.isValidated=1`), wrapped so it never blocks the
+  AIG-contract/email flow; a new WH `prePost` guard carrier-normalizes the address onto the
+  payload before save (TRUE-79533). See the WH per-address purchase guard doc. (mhammontree)
 - 2026-06-29 — Documented the silent-failure AIG warranty-contract interceptor and the
   external log-scan monitor (`_Worker_Monitors_RateEntitlement`, TRUE-79129), including the
   accepted detection limitation that auth-induced failures are not attributable (shared

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

@@ -0,0 +1,140 @@
+---
+title: "Rate Whole Home Warranty Per-Address Purchase Guard"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: rate
+type: client-feature
+status: active
+updated: 2026-07-07
+owners: [mhammontree]
+files:
+  - _underscore/Model/Rate/Entitlement.php
+  - _underscore/Model/Client/Address.php
+  - dbchanges2/Client_Rate/2026-07-07a - WholeHomeWarrantyPerAddressGuard.sql
+related:
+  - clients/rate/profile.md
+  - clients/rate/features/aig-contract-creation.md
+  - ../../../2.0/apps/_underscore/features/address-validation.md
+---
+
+## Summary
+
+A customer may hold **one active Whole Home Warranty (WH) per validated address, globally**
+(across all borrowers). This guard enforces that business rule at purchase time on the Rate
+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:
+
+1. **Requires a service address** from `$payload->contact->primaryContactAddress->address`.
+2. **Hard-blocks** the purchase if
+   [`_Model_Client_Address::validateAddress`](../../../2.0/apps/_underscore/features/address-validation.md)
+   (USPS→FedEx→UPS waterfall) returns `success:false` — no entitlement is created; the error
+   surfaces to the frontend toaster.
+3. **Adopts the carrier-normalized address** (`address1`/`address2`/`city`/`state`/`zipCode`)
+   and writes it back onto the payload, so both the saved address and the AIG contract use the
+   canonical form.
+4. **Hard-blocks a second active WH at the same physical address globally** via
+   `hasActiveWarrantyAtAddress()`.
+
+`postPost` then persists the validated service address after save (sets `Addresses.isValidated=1`
+and `Entitlements.c_serviceAddressId`), wrapped so it never blocks the existing AIG-contract /
+confirmation-email flow.
+
+Ticket: TRUE-79533. Business rule owner: PM Paulina.
+
+## Business rules (decided this session — Mark / Paulina)
+
+- **Invalid address → HARD BLOCK.** An address that fails carrier validation blocks the
+  purchase entirely (no entitlement), surfaced as an API error to the frontend toaster.
+- **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.
+- **Persist the validated address ON the entitlement** (new `c_serviceAddressId` FK) rather
+  than deriving it from the fragile contact-primary-address path, and **backfill** existing WH
+  entitlements so the global rule covers production data already present.
+
+## How it works
+
+1. **`prePost` (PRE/POST interceptor).** Fires only for WH sale items (title LIKE
+   `%warranty%`).
+2. Reads the service address off `$payload->contact->primaryContactAddress->address`; missing
+   address → block.
+3. Calls `_Model_Client_Address::validateAddress`; `success:false` → block. On success, copies
+   the normalized `address1/address2/city/state/zipCode` back onto the payload.
+4. `hasActiveWarrantyAtAddress()` joins `Entitlements` → `Items` (title LIKE `%warranty%`, with
+   WH `Items.id = 3` as an OR fallback) → **active** `Subscriptions` (`isActive = 1 AND
+   dateCancelled IS NULL`) → `Addresses` on the new `c_serviceAddressId` column. A match → block
+   the second active WH.
+   - **The dedup read disables the query cache** (`_Database::useQueryCache(false)`, restored in
+     a `finally`) so it sees rows committed by a just-prior purchase rather than a stale cached
+     result set.
+5. **`postPost`.** After save, persists the validated service address: sets
+   `Addresses.isValidated = 1` and writes `Entitlements.c_serviceAddressId`. This block is
+   wrapped so a failure never interrupts the AIG-contract creation or the confirmation email
+   (see the [AIG contract creation doc](aig-contract-creation.md) — the same `postPost`).
+6. All SQL uses `_Database::escape()` / int-casts — `_Query` has **no bind API** in this path.
+
+## Migration (`dbchanges2/Client_Rate/2026-07-07a - WholeHomeWarrantyPerAddressGuard.sql`)
+
+- Adds `Entitlements.c_serviceAddressId INT NULL` + an index.
+- Guarded (`NOT EXISTS`) registration of `CustomRecordFields` for `c_serviceAddressId`
+  (recordId 191, type **NUMBER**).
+- Guarded registration of the `ApiPayloadInterceptors` PRE/POST rows.
+- A one-time, idempotent backfill of `c_serviceAddressId` for existing WH entitlements, sourced
+  from `Contacts` → `ContactAddresses` → `Addresses`.
+
+## Rate data model (prod-verified 2026-07-07)
+
+- **WH product** = `Items.id 3` / `partNumber 1429124` "Whole Home Warranty - Monthly". Tech
+  products are `Items.id` 1 and 2.
+- **Active-subscription signal is on `Subscriptions`** (`isActive` tinyint default 1,
+  `dateCancelled`, `dateEnd`, `dtRequestToCancel`). `Entitlements` has **no `isActive`**.
+- **Entitlements had no address linkage before this ticket.** `SalesOrders` has
+  `shipToAddressId`/`billToAddressId` but they are NULL for Rate. Before `c_serviceAddressId`,
+  the address was reachable only via `Entitlement.contactId` → `Contacts.primaryContactAddressId`
+  → `ContactAddresses.addressId` → `Addresses`.
+- **Borrower identity** = `Customers.c_borrowerId`.
+- **Core.Records record IDs:** Addresses = 13, Entitlements = 191, Sales orders = 14,
+  Entitlement tickets = 212.
+
+## Frontend contract (delivered by Tanner — TRUE-79825 / 79969 / 79905, toga2-view)
+
+The frontend UI that this guard honors was delivered separately: `components/ValidateAddressModal`,
+`hooks/useValidateAddressFormViewModel`, `pages/ZipValidation`. The FE calls
+`GET /addresses/validateAddress` and reads **`data.addresses.validateAddress`** typed as
+`{ success, error?, address1?, address2?, city?, state?, zipCode?, country? }`. The modal shows
+suggested-vs-entered when `success && address1`, and a "couldn't verify" toaster when
+`success === false`. See the shared
+[address-validation feature](../../../2.0/apps/_underscore/features/address-validation.md) for the
+endpoint mechanics.
+
+## Gotchas / known issues
+
+- **TOCTOU on the uniqueness check (accepted).** The check-then-persist dedup is **not**
+  lock-guarded. Two truly concurrent same-address WH purchases could both pass. Accepted for
+  sequential purchases; documented in code.
+- **AIG carrier vs. AIG tenant.** "AIG" here is the warranty **carrier** behind Rate's Whole
+  Home Warranty — a different codepath from the separate `Client_Aig` / Staples Protection Plan
+  tenant. Do not conflate the two.
+- **`ApiPayloadInterceptors` (Client_Rate) has no `phpMethod` column.** The interceptor method
+  is resolved **by convention** from `(prePostProcessing, httpMethod)`: `PRE+POST → prePost`,
+  `POST+POST → postPost` (matches the framework `[pre|post][HttpMethod]` convention).
+- **`CustomRecordFields.type` enum supports only `STRING`/`NUMBER`** — `c_serviceAddressId` is
+  registered as `NUMBER`.
+- **No `_Query` bind API here** — use `_Database::escape()` / int-casts for all interpolated
+  values.
+
+## Change history
+
+- 2026-07-07 — Built the WH per-address purchase guard (TRUE-79533): `prePost` on
+  `_Model_Rate_Entitlement` hard-blocks invalid addresses and second active WH at the same
+  normalized address (global), adopts the carrier-normalized address onto the payload, and
+  disables the query cache for the committed-read dedup; `postPost` persists the validated
+  service address (`Entitlements.c_serviceAddressId`, `Addresses.isValidated=1`) without blocking
+  the AIG/email flow. Migration adds `c_serviceAddressId` + index, registers the CustomRecordField
+  and PRE/POST interceptors, and backfills existing WH entitlements. (mhammontree)

package/package.json

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