toga-ai 1.0.289 → 1.0.290

package/knowledge/2.0/standards/backend-testing.md

@@ -5,9 +5,12 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-07-02
+updated: 2026-07-08
 owners: [mhammontree]
-files: []
+files:
+  - _underscore/Query.php
+  - _underscore/Database.php
+  - _underscore/Environment.php
 related:
   - ../apps/_underscore/architecture.md
   - ../apps/_underscore/features/per-client-database-connections.md
@@ -27,12 +30,22 @@ From a 2.0 app root (e.g. `worker2`): `chdir` into the app, require Composer aut
 `_underscore.php`, and set `ENVIRONMENT` before bootstrap:
 
 ```php
+putenv('ENVIRONMENT=dev-markhammontree-laptop'); // REQUIRED, before requiring _underscore.php
+                                                 // e.g. dev-<yourname>-laptop — matches your Config/<ENVIRONMENT>.ini
 chdir('/path/to/worker2');
 require 'vendor/autoload.php';
 require '_underscore.php';   // boots Loader/Config/etc.
-// ENVIRONMENT must be set (env var / server) so _Config picks the right INI
 ```
 
+- **`ENVIRONMENT` is mandatory.** The bootstrap uses it to select `worker2/Config/<ENVIRONMENT>.ini`.
+  If it is unset, `_underscore.php` throws *"The environment variable 'ENVIRONMENT' is required and
+  has not been set"* (`_underscore/Environment.php:12`). Set it via `putenv(...)` in the script
+  before the `require`, or export it in the shell.
+- **On Windows the shell is PowerShell** — set env vars as `$env:VAR='x'; php script.php`, **not**
+  the bash `VAR=x php script.php` prefix. The bash-style prefix silently does nothing in
+  PowerShell, so the script falls back to its defaults (a confusing "it ran but used the wrong
+  config" failure).
+
 ## You MUST pin the client DB explicitly
 
 `_underscore::DB_CLIENT` is a **logical alias**, not a schema name — there is no database literally
@@ -51,8 +64,41 @@ Without this, any `Model/Client/*` query resolves the unmapped alias and fails.
 schema you have locally/on the target env (internal testing uses `Client_True` = TOGA Technology).
 Remember the per-client **logs** connection trap too (see the per-client-database-connections doc).
 
+## Commit before you read your own writes (lazy-transaction trap)
+
+Standalone scripts run under `_underscore`'s **lazy-transaction model with a separate read
+connection**, so a write is invisible to a later read — and to the code under test — until it is
+committed. Concretely:
+
+- `_Database::register(..., alias: _underscore::DB_CLIENT)` sets up a pending transaction for that
+  DB. The **first** write (via `_Query`) flips autocommit **OFF** and opens the transaction
+  (`_underscore/Query.php` ~303–304, keyed by the database value passed to `_Query`).
+- INSERTs therefore sit **uncommitted**. A subsequent `SELECT` on the read connection returns
+  nothing, so a read-back-by-marker returns `null` and dependent FK inserts fail (classic symptom:
+  `saleItemId = 0` FK violation).
+
+**Pattern:** after seeding base rows, call
+`_Database::transactionCommit(_underscore::DB_CLIENT)` (`_underscore/Database.php` ~165–212). This
+commits **and** restores `autocommit(true)`, so all later writes — and reads of them — behave
+normally. Order your script:
+
+1. seed base rows →
+2. **commit** →
+3. read ids back →
+4. insert dependent rows →
+5. assert →
+6. cleanup — and **commit the cleanup too**, so the `DELETE`s persist rather than being rolled
+   back when the script exits.
+
+This is the same lazy-transaction write-drop family noted in the `_underscore` architecture doc;
+it bites the standalone-script/verification case specifically. Demonstrated working in
+`test/@Mark/Rate/verify_wholehome_per_address_guard.php`.
+
 ## Rules
 
 - Do not add or assume a PHPUnit suite for 2.0 backend work; write a `test`-repo script instead.
+- Always set `ENVIRONMENT` before bootstrap (PowerShell: `$env:ENVIRONMENT='...'`, or `putenv`).
 - Always pin the concrete `Client_<Id>` schema to `DB_CLIENT` (and logs/archive if the code logs).
+- **Commit seeded rows before you read them back** — the read connection cannot see uncommitted
+  writes; commit cleanup too so it persists.
 - Keep scripts in your per-dev `test` folder; never point them at production databases.

package/knowledge/clients/rate/INDEX.md

@@ -8,5 +8,5 @@
 | [Rate SAML SSO](features/saml-sso.md) | 2.0 | Rate uses Azure AD as its IdP (`login.rate.com`). | _underscore/Model/Rate/ClientAuthentication.php, saml/Controller/Index.php, toga2-view/src/hooks/useAuthenticationFlow.ts |
 | [Service Card Entitlement Display](features/service-card-entitlements.md) | 2.0 | Rate's home and services pages display one service card per purchased entitlement. | src/components/ServiceCard/ServiceCard.tsx, src/components/ServiceCard/index.ts, src/hooks/useBundleServices.ts, src/pages/Home/api/homeApi.ts, src/pages/Home/view/HomePage.tsx, src/pages/Home/viewModels/useHomePageViewModel.ts, src/pages/Services/view/ServicesPage.tsx, src/pages/Services/viewModels/useServicePageViewModel.ts |
 | [Rate Service-Purchase Confirmation Emails (Tech / Warranty)](features/service-purchase-emails.md) | 2.0 | When a Rate customer purchases a service, a confirmation email is sent. | _underscore/Model/Rate/Entitlement.php, worker2/Worker/Notification/EmailTemplate.php, dbchanges2/Client_Rate/2026-06-30a - Rate purchase email templates.sql |
-| [Rate Whole Home Warranty Per-Address Purchase Guard](features/whole-home-warranty-purchase-guard.md) | 2.0 | 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 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, test/@Mark/Rate/verify_wholehome_per_address_guard.php |
 | [Rate](profile.md) | 2.0 | Rate is a mortgage/lending client. |  |

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

@@ -6,12 +6,13 @@ project: _Underscore
 client: rate
 type: client-feature
 status: active
-updated: 2026-07-07
+updated: 2026-07-08
 owners: [mhammontree]
 files:
   - _underscore/Model/Rate/Entitlement.php
   - _underscore/Model/Client/Address.php
   - dbchanges2/Client_Rate/2026-07-07a - WholeHomeWarrantyPerAddressGuard.sql
+  - test/@Mark/Rate/verify_wholehome_per_address_guard.php
 related:
   - clients/rate/profile.md
   - clients/rate/features/aig-contract-creation.md
@@ -113,6 +114,17 @@ suggested-vs-entered when `success && address1`, and a "couldn't verify" toaster
 [address-validation feature](../../../2.0/apps/_underscore/features/address-validation.md) for the
 endpoint mechanics.
 
+## Verification
+
+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
+`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**.
+
 ## Gotchas / known issues
 
 - **TOCTOU on the uniqueness check (accepted).** The check-then-persist dedup is **not**
@@ -131,6 +143,9 @@ endpoint mechanics.
 
 ## Change history
 
+- 2026-07-08 — Added a backend verification script
+  (`test/@Mark/Rate/verify_wholehome_per_address_guard.php`, 18/18 pass against the migrated
+  `Client_Rate` schema) and a Verification pointer. (mhammontree)
 - 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

package/package.json

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