toga-ai 1.0.288 → 1.0.290

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

@@ -8,6 +8,7 @@
 | [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 |
+| [_Component_*/_Model_* project-namespace registration (autoloader) & backslash-qualify traps](features/component-model-namespace-registration.md) | Every **project-local** `_Component_*` and `_Model_*` class in a 2.0 app **must declare the project namespace** at the top of the file: ```php namespace <NAMESP | _underscore/Loader.php, worker2/_.php, api2/_.php, worker2/Component/Forecast/Db/Db.php, worker2/Component/Forecast/SaleImport/SaleImport.php, api2/Component/Api/Netsuite/Netsuite.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 |
 | [Record-Changed Event Publishing (_Event::publish to SQS)](features/event-publish-sqs.md) | `_Event::publish()` (in `_underscore/Event.php`) is the PHP side of the real-time event pipeline. | _underscore/Event.php |

package/knowledge/2.0/apps/_underscore/features/component-model-namespace-registration.md

@@ -0,0 +1,102 @@
+---
+title: "_Component_*/_Model_* project-namespace registration (autoloader) & backslash-qualify traps"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-07-08
+owners: [dfranks]
+files:
+  - _underscore/Loader.php
+  - worker2/_.php
+  - api2/_.php
+  - worker2/Component/Forecast/Db/Db.php
+  - worker2/Component/Forecast/SaleImport/SaleImport.php
+  - api2/Component/Api/Netsuite/Netsuite.php
+related:
+  - ../architecture.md
+  - ./forecast-sale-import.md
+---
+
+## Summary
+Every **project-local** `_Component_*` and `_Model_*` class in a 2.0 app **must declare the
+project namespace** at the top of the file:
+
+```php
+namespace <NAMESPACE>;   // worker2 → 'worker', api2 → 'api'
+```
+
+where `<NAMESPACE>` is the value of that project's `_.php` `const NAMESPACE` (worker2 =
+`'worker'`, api2 = `'api'`). The `namespace` declaration **IS the "registration"** — there
+is no config toggle. If the class is declared in the **global** namespace instead, the
+`_underscore` autoloader throws at **class-load (runtime)**:
+
+> The namespace for '`<Class>`' located in '`<path>`' has not been defined which is
+> prohibited for all _Model and _Component classes. Define the namespace for this class and
+> try again.
+
+**This is NOT caught by `php -l`** (parse-only) — it only surfaces at autoload/runtime, so
+lint-clean code can still fatally throw on the first request that touches the class.
+
+## How it works — `_underscore/Loader.php` (lines ~71-83)
+For a project-local `_Component_*` / `_Model_*` class the autoloader:
+1. `require`s the local file.
+2. Checks whether the class **also** exists under the project namespace
+   (`<NAMESPACE>\<Class>`).
+3. **If yes** → `eval`s a bridge class in the global namespace
+   (`class <Class> extends <NAMESPACE>\<Class> {}`, Loader.php:79-80) so callers can use the
+   bare `_Component_Foo` name.
+4. **If no** (class was declared globally, so `<NAMESPACE>\<Class>` doesn't exist) → **throws**
+   the "namespace … has not been defined" error above.
+
+**Correct precedent to copy:** `api2/Component/Api/Netsuite/Netsuite.php` —
+`namespace api;` + `class _Component_Api_Netsuite extends \_Component` + `\_Config::netsuite(...)`,
+`new \_ApiRequest(...)`.
+
+### Framework references inside a namespaced file — what resolves vs. what must be backslash-qualified
+Once the file is in `namespace <NAMESPACE>;`, **static calls and constants** to framework
+classes resolve transparently via the autoloader's namespace fallback (Loader.php ~94-120),
+bridged as `<NAMESPACE>\_X` → the framework class — e.g. `_Time::convert(...)`,
+`_underscore::DB_FORECAST`, `_Component_Api_Netsuite::send(...)`, `new _Query(...)` all work
+unqualified.
+
+**Three constructs do NOT get that treatment and MUST be backslash-qualified:**
+- `catch (\Exception $e)` / `catch (\RuntimeException $e)` — unqualified `catch (Exception $e)`
+  resolves to the non-existent `<NAMESPACE>\Exception` and silently no-matches (or fatals).
+  **This silent-swallow `catch` is the most dangerous / easiest-to-miss line** — the block
+  never catches, so error handling quietly does nothing.
+- `new \Exception(...)` / `throw new \RuntimeException(...)` — same reason.
+- `extends \_Component` (and `extends \_Model` etc.) — the base class in the class declaration
+  must be backslash-qualified.
+
+## Why this matters — the Forecast SALES drift root cause
+This mechanism was the root cause of the Forecast **SALES** drift observed after a worker2
+push: `_Component_Forecast_SaleImport` and `_Component_Forecast_Db` had been declared in the
+**global** namespace, so every NetSuite sales/invoice/opportunity webhook **fatally threw at
+autoload before writing to `Forecast.Sales`**. Because NetSuite replays edits across old
+transactions, the symptom **presented as ~7 months of historical drift** rather than as a
+"new code broken" failure — a misleading symptom that this mechanism explains.
+
+(The engine ultimately lives under `_underscore` — see the
+[Forecast.Sales import engine doc](./forecast-sale-import.md) — precisely because a
+`_Component_*` class loaded from a project path is rejected; but even a legitimately
+project-local `_Component_*`/`_Model_*` must still declare the project namespace.)
+
+## Gotchas / known issues
+- `php -l` will **not** catch a missing/global namespace or an unqualified `catch`/`throw`/
+  `extends` — boot the class (autoload it) to verify. A wrong autoload path is likewise a
+  runtime-only failure.
+- A global-namespace `_Component_*`/`_Model_*` fails **loudly** (the throw above). An
+  unqualified `catch (Exception $e)` fails **silently** — the more insidious of the two.
+
+## Change history
+- 2026-07-08 — Documented the `_Component_*`/`_Model_*` project-namespace registration
+  requirement (Loader.php eval-bridge mechanism, ~71-83), the runtime-only failure mode (not
+  caught by `php -l`), and the three constructs that must be backslash-qualified inside a
+  namespaced file (`catch`/`throw`/`new \Exception`, `extends \_Component`). Root-caused the
+  Forecast SALES drift to `_Component_Forecast_SaleImport`/`_Component_Forecast_Db` declared
+  in the global namespace (webhooks threw at autoload before writing; presented as 7-month
+  historical drift because NetSuite replays edits). Correct precedent:
+  `api2/Component/Api/Netsuite/Netsuite.php`. (dfranks)

package/knowledge/2.0/apps/_underscore/features/forecast-sale-import.md

@@ -38,6 +38,7 @@ related:
   - ../../worker2/features/netsuite-salesorder-open-orders-sync.md
   - ../../worker2/features/netsuite-supporting-record-webhook-importer.md
   - ./netsuite-rest-client.md
+  - ./component-model-namespace-registration.md
 ---
 
 ## Summary
@@ -135,7 +136,14 @@ This is the **opposite of the legacy cron**, which reads the pre-signed listSale
 (already `-foreignamount`) and so applies the factor **only** to the synthetic shipping
 line. **Do not copy the cron's sign handling into the webhook** — it reintroduces the
 ~$470K credit-memo sign bug (credits stored positive). The cron is not authoritative for
-the raw-REST path. Confirmed end-to-end against the local Forecast mirror (creditMemo
+the raw-REST path.
+
+> **Do not confuse this line-amount/revenue sign with the `amountDue` "store raw positive"
+> decision (TRUE-78923).** The "store raw positive / don't sign-flip credit memos & refunds"
+> guidance applies **only to `amountDue`** (which this importer does not write) — it does
+> **NOT** apply to the line `amount`/revenue sign. For revenue, credit memos + cash refunds
+> **must** land NEGATIVE and invoices + cash sales POSITIVE in `Forecast.Sales`; that is the
+> stored contract. Mis-carrying the amountDue rule onto revenue would store credits positive. Confirmed end-to-end against the local Forecast mirror (creditMemo
 revenue stored -350..-600; cashRefund revenue -885 / profit -78; invoice positive).
 
 > A reviewer may flag "profit double-signs the factor" — false positive:
@@ -481,10 +489,25 @@ record is deleted in NetSuite.)
   (e.g. `./` under worker2) with "namespace … has not been defined" — at **class-load
   (runtime), not `php -l`**. So this engine lives in `_underscore` next to
   `_Component_Forecast_Db` even though only worker2 uses it; it references the worker2 class
-  `_Worker_Netsuite_Item`, resolved lazily at runtime in the worker2 context.
+  `_Worker_Netsuite_Item`, resolved lazily at runtime in the worker2 context. **A
+  legitimately project-local `_Component_*`/`_Model_*` (e.g. the worker2 copies of these
+  classes) must still declare `namespace worker;` or it throws the same error at autoload —
+  and this exact global-namespace mistake caused the SALES drift (webhooks fatally threw
+  before writing, presenting as 7-month historical drift). See the
+  [namespace-registration doc](./component-model-namespace-registration.md) for the
+  eval-bridge mechanism and the `catch`/`throw`/`extends` backslash-qualify traps.**
 - The cron's sign handling is not portable here — see Sign convention.
 
 ## Change history
+- 2026-07-08 — **Clarified the revenue sign convention is NOT the `amountDue` "store raw
+  positive" rule.** The TRUE-78923 "don't sign-flip credit memos/refunds" guidance applies
+  only to `amountDue` (which this importer does not write); the line `amount`/revenue sign
+  contract is unchanged — credit memos + cash refunds NEGATIVE, invoices + cash sales
+  POSITIVE. Also cross-linked the new
+  [`_Component_*`/`_Model_*` namespace-registration doc](./component-model-namespace-registration.md):
+  a global-namespace declaration of `_Component_Forecast_SaleImport`/`_Component_Forecast_Db`
+  was the root cause of the SALES drift (webhooks threw at autoload before writing; presented
+  as 7-month historical drift because NetSuite replays edits). (dfranks)
 - 2026-07-07 — **Documented the AMQ enqueuer's line-field inline-edit blind spot** (Forecast2 SALES
   profit-drift forensics; invoice 6715127 / 2026-02-20 / $3,392.70). Editing a **sublist LINE
   field** (e.g. cost `TRANLINE.MCOSTESTIMATE`) inline in the NetSuite UI raises **no** record UE

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

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 25 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 26 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,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.288",
+  "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",