toga-ai 1.0.217 → 1.0.219

package/knowledge/1.0/apps/test/INDEX.md

@@ -8,6 +8,7 @@
 | [Create Elastic Beanstalk Environment (script)](features/create-elastic-beanstalk.md) | `team/aws/create_elastic_beanstalk.php` is a **standalone** (no `App_` framework) constants-driven PHP generator. | test/team/aws/create_elastic_beanstalk.php |
 | [Developer Generators (password, UUID)](features/dev-generators.md) | Two tiny **1.0 `App_` framework** convenience scripts for everyday developer needs. | test/team/generate_password.php, test/team/uuid.php |
 | [Forecast vs NetSuite Discrepancy Analysis](features/forecast-netsuite-discrepancy-analysis.md) | `team/forecast-netsuite/discrepancy_analysis.php` detects discrepancies between our **Forecast database** and **NetSuite** (the source of truth for all sales da | test/team/forecast-netsuite/discrepancy_analysis.php |
+| [@goagilant.com → @togatech.com Email-Domain Migration (1.0 + 2.0)](features/goagilant-to-togatech-email-migration.md) | Reference + technique for migrating the company email domain `@goagilant.com` → `@togatech.com` across **both** platforms. | migrate_goagilant_to_togatech_2026-06-26.sql, migrate_goagilant_to_togatech_LEGACY_2026-06-26.sql |
 | [TableView Builder (2.0 TableViews SQL generator)](features/tableview-builder.md) | `team/tableViewBuilder/` generates SQL `INSERT` statements for the **2.0 `TableViews`**, `TableViewFields`, and `TableViewJoins` tables from a plain SQL `SELECT | test/team/tableViewBuilder/TableViewGenerator.php, test/team/tableViewBuilder/index.php, test/team/tableViewBuilder/Instructions.md |
 | [Talos Knowledge Base Pipeline (Uploader + Processor)](features/talos-kb-pipeline.md) | `team/talos/` holds the two-script web tooling that feeds the **TOGa Talos** (TOGa IQ) AI knowledge bases. | test/team/talos/kb_uploader.php, test/team/talos/kb_processor.php, test/team/talos/kb_processor.ini |
 | [TOGa 2.0 Client Onboarding SQL Generator](features/toga2-client-onboarding-sql.md) | `team/generate_toga2_onboarding_sql.php` generates the SQL needed to **onboard a new client** onto the 2.0 platform. | test/team/generate_toga2_onboarding_sql.php |

package/knowledge/1.0/apps/test/architecture.md

@@ -21,6 +21,7 @@ related:
   - ./features/url-domain-markdown-document.md
   - ./features/dev-generators.md
   - ./features/talos-kb-pipeline.md
+  - ./features/goagilant-to-togatech-email-migration.md
 ---
 
 ## Summary
@@ -83,6 +84,7 @@ manually against the target database; they do not execute changes themselves.
 | `generate_toga2_user_access_sql.php` | 1.0 | 2.0 client DBs | [toga2-user-cross-client-access-sql](./features/toga2-user-cross-client-access-sql.md) |
 | `generate_password.php`, `uuid.php` | 1.0 | dev utility | [dev-generators](./features/dev-generators.md) |
 | `talos/kb_uploader.php`, `talos/kb_processor.php` | standalone | S3 + AWS Bedrock KBs | [talos-kb-pipeline](./features/talos-kb-pipeline.md) |
+| `migrate_goagilant_to_togatech_*.sql` | standalone | 2.0 `Client_` DBs + 1.0 schemas | [goagilant-to-togatech-email-migration](./features/goagilant-to-togatech-email-migration.md) |
 
 **Retired / not documented:** `team/DOA_gitbook/` is being retired.
 
@@ -91,3 +93,5 @@ manually against the target database; they do not execute changes themselves.
 - 2026-06-16 — Initial capture of the `team/` folder. Registered repo in `registry.json`.
 - 2026-06-22 — Un-retired `team/DOA_talos/` → `team/talos/`; documented its uploader +
   processor in [talos-kb-pipeline](./features/talos-kb-pipeline.md).
+- 2026-06-26 — Documented the @goagilant.com → @togatech.com email-domain migration SQL
+  artifacts in [goagilant-to-togatech-email-migration](./features/goagilant-to-togatech-email-migration.md).

package/knowledge/1.0/apps/test/features/goagilant-to-togatech-email-migration.md

@@ -0,0 +1,134 @@
+---
+title: "@goagilant.com → @togatech.com Email-Domain Migration (1.0 + 2.0)"
+framework: "1.0"
+repo: test
+project: Test
+client: shared
+type: feature
+status: active
+updated: 2026-06-26
+owners: [bala]
+files:
+  - migrate_goagilant_to_togatech_2026-06-26.sql
+  - migrate_goagilant_to_togatech_LEGACY_2026-06-26.sql
+related:
+  - ../architecture.md
+  - ./2-0-deployment-client-sql.md
+  - ../../../2.0/apps/_underscore/features/email-template-sending.md
+  - ../../../2.0/apps/_underscore/features/per-client-database-connections.md
+---
+
+## Summary
+
+Reference + technique for migrating the company email domain `@goagilant.com` →
+`@togatech.com` across **both** platforms. Two standalone SQL artifacts (run manually
+against the right cluster, not framework code) were produced:
+
+- `migrate_goagilant_to_togatech_2026-06-26.sql` — 2.0 prod, per-tenant `Client_` DBs.
+- `migrate_goagilant_to_togatech_LEGACY_2026-06-26.sql` — 1.0 legacy.
+
+The durable value is the **email-column blast-radius map** for each environment and the
+**two collision gotchas** that make a blanket find/replace unsafe. Use this before any
+future email-domain change.
+
+## Where @goagilant.com emails live
+
+### 2.0 prod (per-tenant `Client_` DBs, prod-client cluster)
+
+Value columns that actually held `@goagilant.com` data:
+
+| Column | Notes |
+|---|---|
+| `Users.email` | **UNIQUE** — identity logins. See Client_True gotcha. |
+| `ContactEmailAddresses.emailAddress` | |
+| `EmailTemplates.sendFromEmailAddress` | Present in **all 32 clients**; outbound `From:` — deliverability-sensitive (sender-verification gate below). |
+| `IntegrationsEmail.fromEmailAddress` | Outbound `From:` — deliverability-sensitive. |
+| `SalesOrderEmailAddresses.emailAddress` | Composite UNIQUE `(salesOrderId, emailAddress)`. |
+| `EmailTemplateOutgoingEmailAddresses.emailAddress` | Composite UNIQUE. |
+
+Columns that exist but held **zero** `@goagilant.com` data (skip):
+`Campaigns.bookingEmailAddress`, `LocationEmailAddresses.emailAddress`,
+`IntegrationsEmailOutgoingEmailAddresses.emailAddress`.
+
+`ContactAttempts.c_contactEmail` exists **only** in `Client_True` (BDR).
+
+Tenants with `Users.email` hits included Compass, CompassCanada, Managelife, Quad, Growrk,
+Nychh, Prudential, Aig, Endeavorhealth, Erau, Masonite, Rate, Spglobal, Towfoundation, Wje,
+Wmchealth, Ynhh, plus True (special-cased).
+
+### 1.0 legacy
+
+| Table | Hits | Notes |
+|---|---|---|
+| `TOGA.Users.email` | 1117 goagilant | Main platform login. **NOT unique** (PRIMARY on `id` only). togatech migration already ~half done: 1077 togatech rows exist; 7 goagilant overlap a togatech local-part. |
+| `TOGA_<tenant>.ClientUsers.email` | 0 goagilant | Client-portal logins — clean across all 14 tenants. |
+| `TOGA_<tenant>.Contacts.emailAddress` | ~255 | CRM. `relayEmailAddress` = 0 everywhere. |
+| `Vision.Users` | 343 | Sibling-app login, 0 togatech twins. |
+| `RetailServices.DashboardUsers` | 6 | 0 togatech twins. |
+| `ITADPortal.Users` | 3 | 0 togatech twins. |
+| `TOGaDeskAdmin.users` | 2 | 0 togatech twins. |
+
+**Not migrated** (high-volume ancillary, out of scope): helpdesk `TOGaDeskSupport.tickets`
+(15725), `Common` directory (~3700), RetailServices customer data, Netsuite/Store. The
+**Advisor** and **GoAgilant (WordPress)** schemas are not queryable via the toga-db MCP tool
+and were not assessed here.
+
+## How it works (safe-rename technique)
+
+Swap **only** the 14-char domain suffix, preserving the local-part exactly:
+
+```sql
+UPDATE SomeTable
+SET col = CONCAT(LEFT(col, CHAR_LENGTH(col) - 14), '@togatech.com')
+WHERE col LIKE '%@goagilant.com';
+```
+
+Why not `REPLACE()`: `REPLACE` is case-sensitive (misses `@GoAgilant.com`) and can touch a
+mid-string match. `LEFT`/`CONCAT` on the trailing 14 chars touches only the domain and keeps
+apostrophes/odd local-parts intact (e.g. `do'connell@`). The `LIKE` is the natural
+case-insensitive guard for the match.
+
+For the non-unique 1.0 `TOGA.Users`, a guarded variant uses `NOT EXISTS` against a
+materialized derived table of existing `@togatech.com` addresses, so the 7 would-be
+duplicate logins are skipped rather than creating colliding identities.
+
+## Scope (explicit developer instructions)
+
+- **2.0:** exclude `Client_True.Users` (see gotcha); still migrate True's other email tables.
+- **1.0:** scoped to **USERS + CONTACTS only** — explicitly exclude `Customers`,
+  `SMBContracts` (contracts/work orders), and send-from in 1.0.
+- **Never** touch any `*Logs*` schemas.
+
+## Sender-address gate (deliverability)
+
+`EmailTemplates.sendFromEmailAddress` (~118 rows across all 2.0 clients) and
+`IntegrationsEmail.fromEmailAddress` change the outbound `From:` domain. These were gated
+as a separate step pending `togatech.com` sender verification (SPF/DKIM/DMARC). The domain
+was **confirmed verified 2026-06-26**, so the sender-address step is cleared to run. Do not
+flip a `From:` domain ahead of sender verification — it breaks deliverability.
+
+## Gotchas
+
+- **Client_True (2.0) UNIQUE twins.** `Users.email` is UNIQUE. Of 343 `@goagilant.com`
+  users, **325 already have a pre-staged `@togatech.com` twin** (twins mostly never logged
+  in, `dtLastLogin` NULL — a togatech cutover was partially staged). A blanket rename
+  collides on the UNIQUE constraint (fails, or with `IGNORE` **silently skips 325**). Of the
+  18 no-twin rows, ~13 are service/SFTP/support accounts (`odpsftp@`, `staplessftp@`,
+  `support@`, …) whose rename could break integrations. **Decision:** exclude
+  `Client_True.Users.email` from the migration; migrate only True's 64 non-identity rows
+  (ContactEmailAddresses 56, Campaigns 1, ContactAttempts 1, EmailTemplates.sendFromEmailAddress
+  6), which carry no UNIQUE-on-email risk.
+- **Legacy `TOGA.Users` is non-unique and half-migrated.** PRIMARY is on `id` only, so a
+  rename can produce duplicate login emails. 1077 togatech rows already exist and 7 goagilant
+  rows overlap a togatech local-part — use the `NOT EXISTS`-guarded variant to skip those 7.
+- **Run against the right cluster.** 2.0 lives in per-tenant `Client_` DBs on the prod-client
+  cluster; 1.0 in `TOGA` / `TOGA_<tenant>` / sibling-app schemas. Review the generated SQL
+  before executing — these are manual-run artifacts, nothing auto-executes.
+
+## Change history
+
+- 2026-06-26 — Initial capture. Mapped 2.0 + 1.0 email columns, recorded the Client_True
+  UNIQUE-twin and legacy non-unique-login collision gotchas, the LEFT/CONCAT safe-rename
+  technique, scope exclusions, and the cleared sender-verification gate. (bala)
+</content>
+</invoke>

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

@@ -7,7 +7,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 |
 | [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/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.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 |
-| [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | _underscore/Component/Forecast/SaleImport/SaleImport.php, _underscore/Component/Forecast/Db/Db.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/JournalEntry.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Forecast/2026-06-26a - Add journalEntry to Sales transaction type enum.sql, test/@dave/test_invoice_lifecycle.php, test/@dave/test_je_lifecycle.php, test/@dave/test_creditmemo_lifecycle.php, test/@dave/test_cashsale_lifecycle.php, test/@dave/test_cashrefund_lifecycle.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
+| [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | _underscore/Component/Forecast/SaleImport/SaleImport.php, _underscore/Component/Forecast/Db/Db.php, _underscore/Component/Api/Netsuite/Netsuite.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/JournalEntry.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Forecast/2026-06-26a - Add journalEntry to Sales transaction type enum.sql, test/@dave/test_invoice_lifecycle.php, test/@dave/test_je_lifecycle.php, test/@dave/test_creditmemo_lifecycle.php, test/@dave/test_cashsale_lifecycle.php, test/@dave/test_cashrefund_lifecycle.php, test/@dave/test_fetchrecord_routes.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
 | [_Model magic-field access (__get without __isset)](features/model-magic-field-access.md) | `_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`. | _underscore/Model/Core/Model.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php |

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

@@ -11,6 +11,7 @@ owners: [dfranks]
 files:
   - _underscore/Component/Forecast/SaleImport/SaleImport.php
   - _underscore/Component/Forecast/Db/Db.php
+  - _underscore/Component/Api/Netsuite/Netsuite.php
   - worker2/Worker/Netsuite/Invoice.php
   - worker2/Worker/Netsuite/CashSale.php
   - worker2/Worker/Netsuite/CreditMemo.php
@@ -24,6 +25,7 @@ files:
   - test/@dave/test_creditmemo_lifecycle.php
   - test/@dave/test_cashsale_lifecycle.php
   - test/@dave/test_cashrefund_lifecycle.php
+  - test/@dave/test_fetchrecord_routes.php
   - test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js
   - test/@dave/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js
 related:
@@ -71,7 +73,7 @@ Engine public surface: `sync(int $internalId, string $type)` and
 
 ## How it works
 Per-record flow in `sync`:
-1. REST GET the record (`expandSubResources=true`) via `_Component_Forecast_Db::fetchRecord`.
+1. REST GET the record (`expandSubResources=true`) via `_Component_Api_Netsuite::fetchRecord`.
 2. **Per-type status gate** → if excluded, call `removeAll` and stop. Exclusions: invoice
    `Voided`/`Rejected`; cashSale `Unapproved Payment`; creditMemo `Voided`; cashRefund has
    no gate. **A cashSale created via REST lands in status `Deposited`** (NOT the excluded
@@ -88,14 +90,32 @@ Per-record flow in `sync`:
 `removeAll(internalId)` deletes all rows for that transaction (used by delete events and by
 the status gate).
 
-### Shared helpers on `_Component_Forecast_Db` (dedup)
-- `fetchRecord(route, label)` — NS REST GET + decode.
-- `collectItemLines(record)` + `nextPageRoute(links)` — `rel=next` sublist pagination.
+### Shared NS helpers — `fetchRecord` lives on `_Component_Api_Netsuite`, the rest on `_Component_Forecast_Db`
+- **`_Component_Api_Netsuite::fetchRecord(route, label)`** — NS REST GET + decode. **Moved
+  here** (beside `createRecord`) from `_Component_Forecast_Db` — it is a generic REST read,
+  not Forecast-specific, so it belongs with the other REST primitives. **Verify the class
+  before relying on it** (it was relocated this session). The **7 callers** were all
+  reprefixed to `_Component_Api_Netsuite::fetchRecord`: `SaleImport.php` ×2, `Opportunity.php`
+  ×3, `SalesOrder.php` ×2 (static git-grep: zero stale `_Component_Forecast_Db::fetchRecord`
+  refs, all 7 resolve, lint clean; runtime-verified across all 5 SaleImport types +
+  opportunity/employee/salesOrder routes via `test_fetchrecord_routes.php`).
+- **Still on `_Component_Forecast_Db`** (Forecast-specific): `collectItemLines(record)` +
+  `nextPageRoute(links)` (`rel=next` sublist pagination), `lookupId`, `toSqlDate`.
 
 `Opportunity.php` and `SalesOrder.php` were refactored onto these shared versions; their
 private `fetchRecord`/`collectAllItemLines`/`nextPageRoute` copies (and SalesOrder's
 orphaned `MAX_SUBLIST_PAGES` const) were deleted.
 
+> **Process gotcha — enumerate callers of these shared NS helpers with `git grep`, not the
+> fuzzy/agent search.** Any move/rename of `_Component_Api_Netsuite::createRecord` /
+> `fetchRecord` (or the other shared NS helpers) must build its caller inventory with
+> `git grep -nF` **per repo** — the fuzzy search tool silently **missed**
+> `worker2/Worker/Netsuite/SalesOrder.php:925` (`createRecord`, the SalesOrder SOAP→REST
+> outbound push — a real **production** caller) on a first pass, producing a wrong "zero
+> callers / test-only" conclusion and a broken refactor that had to be reverted. Search
+> case-insensitively for `::method`, `function method`, and string/callable forms; verify
+> **zero stale refs** after editing.
+
 ## Sign convention (the load-bearing decision)
 The **raw REST record** returns each line `amount`/`costEstimate` **POSITIVE for all four
 types** (verified by live probe 2026-06-24 against NS account 1095849: creditMemo lines
@@ -218,28 +238,103 @@ events as specific **subtypes** (`inventoryItem`, `nonInventoryResaleItem`, `kit
 would be needed only for a future real-time item webhook, **not** for this Sales importer
 (which keeps items fresh via the hourly item pull cron plus the inline self-heal).
 
-## Local testing harness (`test/@dave/test_invoice_lifecycle.php`)
-A CLI that boots worker2/_underscore (chdir to `worker2/` then `require index.php`) and drives a
-**full NetSuite invoice lifecycle** through the live `_underscore` REST client
-(`_Component_Api_Netsuite`) to exercise this importer end-to-end against a local Forecast mirror.
-Actions: `check | create | get | update | delete | sync | recent | amq | deployments | locations`.
-
-- **Fixture:** customer **58** ("8 Test Company") + item **103741** ("Test Other Charge for Sale",
-  maps to local `Forecast.Items` id 25), **rate 0** → a **$0 invoice that still yields one Sales
-  row** (the engine does **not** skip a $0 line — revenue `0.00` is written; same as the cron's
-  Sales section). Confirms create→insert, edit→update (tracked-column change-detection), and
-  delete→`removeAll` all land in local `Forecast.Sales`.
-- It carries its **own** `createInvoiceRecord()` that POSTs via `_ApiRequest` and parses the
-  `Location` header with a **correct** regex (delimiter `~`) — a deliberate workaround for the live
-  `_Component_Api_Netsuite::createRecord()` `#`-delimiter bug (see the
-  [REST client doc](./netsuite-rest-client.md)); the framework was **not** edited this session.
-- `amq` action SuiteQLs the AMQ custom record; `deployments` SuiteQLs `scriptdeployment`+`script`
-  to show which enqueuer fires per record type (used to find the dual-deployment trap below).
-- **Per-type siblings** `test_creditmemo_lifecycle.php`, `test_cashsale_lifecycle.php`,
-  `test_cashrefund_lifecycle.php` (and `test_je_lifecycle.php`) mirror this harness, each with its
-  own `create()` POSTing via `_ApiRequest` with the `~`-delimited Location regex workaround.
-  **cashRefund and creditMemo require a header-level location** on create. The create webhook can
-  lag **~20s** before the row appears (read-after-write/processing) — wait before asserting.
+## E2E testing playbook + harness inventory (run this cold)
+This section is the reusable procedure for verifying the NetSuite → `Forecast.Sales` path
+end-to-end against a **local** Forecast mirror. It is written to be runnable in a future
+session with no prior context.
+
+### Harness inventory (`test/@dave/`, all PHP)
+All harnesses boot worker2/_underscore by `chdir('C:/Users/dfranks/www/worker2'); require
+'index.php';` and drive the live `_underscore` REST client (`_Component_Api_Netsuite`).
+**Run them with xampp8 PHP 8.0:** `C:\xampp8\php\php.exe test/@dave/<harness>.php <action> …`
+(local `_underscore` floor is PHP 8.0.0).
+
+| Harness | Type | Actions |
+|---|---|---|
+| `test_invoice_lifecycle.php` | invoice | `check`, `create`, `get <id>`, `sync <id>`, `update <id> <date>`, `delete <id>`, `recent` (plus `amq`/`deployments`/`locations` SuiteQL probes) |
+| `test_creditmemo_lifecycle.php` | creditMemo | same per-type action set |
+| `test_cashsale_lifecycle.php` | cashSale | same per-type action set |
+| `test_cashrefund_lifecycle.php` | cashRefund | same per-type action set |
+| `test_je_lifecycle.php` | journalEntry | per-type set **plus** `sync` (`syncJournalEntry`) and `remove` (`removeAllJournalEntry`, direct); `create` makes a **balanced reversing JE** |
+| `test_fetchrecord_routes.php` | **read-only probe** | calls `_Component_Api_Netsuite::fetchRecord` against a real opportunity/employee/salesOrder id — proves that method per route, **no side effects** |
+
+**Per-type actions explained:**
+- `check` — boot + OAuth only, **no writes** (smoke test connectivity/creds).
+- `create` — create a real record in NetSuite (tiny `$0`/`$0.01`).
+- `get <id>` — REST GET the record.
+- `sync <id>` — **DIRECT** `_Component_Forecast_SaleImport::sync()` (or `syncJournalEntry()`)
+  against NetSuite reads, **local, no webhook**. This is the local-only execution path.
+- `update <id> <date>` — PATCH `tranDate` (a tracked field) to exercise edit→update.
+- `delete <id>` — delete the record in NetSuite.
+- `recent` — list recent records of that type.
+
+Each harness carries its **own** local create helper that POSTs via `_ApiRequest` and parses
+the `Location` header with a **correct `~`-delimited regex** — a deliberate workaround for the
+live `_Component_Api_Netsuite::createRecord()` `#`-delimiter bug (still unfixed; see the
+[REST client doc](./netsuite-rest-client.md)). The framework is **not** edited to test.
+
+### The 6-step lifecycle pattern (every type)
+1. **create** → a real NetSuite record.
+2. **verify** the local `forecast.Sales` row(s) appeared.
+3. **update** the `tranDate`.
+4. **verify** the update landed (tracked-column change-detection).
+5. **delete** the record.
+6. **verify** the local row is gone (`removeAll`).
+
+Poll the **local** Forecast DB between steps:
+`C:\xampp8\mysql\bin\mysql.exe -u root` → db **`forecast`**, table **`Sales`** (filter on the
+test internalId, or customerId `2` / itemId `25`).
+
+### Two execution modes
+- **(a) WEBHOOK path** — NS create → AMQ enqueuer → ngrok → local worker2 → engine. Requires:
+  the **dev** AMQ enqueuer **deployed on each record type under test** with its **AUDIENCE
+  including the REST/M2M integration user** (Execute-As-Role does **not** control triggering —
+  AUDIENCE does); the **prod** enqueuer left **UNDEPLOYED** for isolation; and **ngrok up** at
+  the enqueuer's `DEV_OVERRIDE` endpoint. Exercises the real inbound path.
+- **(b) LOCAL-ONLY path** (use when deployments are off / you can't touch NetSuite scripts) —
+  skip the webhook entirely: call the harness **`sync`** action, which runs
+  `_Component_Forecast_SaleImport::sync()` / `syncJournalEntry()` **directly** against NetSuite
+  reads. Exercises the same import + `fetchRecord` with **no enqueuer/ngrok dependency**.
+
+### Fixtures
+- Customer **58** ("8 Test Company") → local `forecast.Customers` id **2**.
+- Item **103741** ("Test Other Charge for Sale") → local `forecast.Items` id **25**.
+- Location **5** ("Main") — required as a **header-level** field on creditMemo/cashSale/cashRefund
+  and **line-level** on invoice.
+- **JE fixture:** subsidiary **1**; accounts **245** (Product Revenue / Income), **248**
+  (COGS Product / COGS), **215** (Clearing - CSS — ignored, neither revenue nor cost); set a
+  `reversalDate` so NetSuite auto-creates the reversal.
+
+### Expected local revenue signs / row outcomes
+- **invoice** → `+` (a **$0** invoice still writes **one** row, revenue `0.00` — the engine does
+  not skip a $0 line).
+- **cashSale** → `+`; status must be **`Deposited`** (a REST-created cash sale lands Deposited,
+  **not** the excluded `Unapproved Payment`).
+- **creditMemo** → `−`.
+- **cashRefund** → `−`.
+- **JE** → `revenue = Σ(credit − debit)` over revenue-acct lines, `cost = Σ(debit − credit)`
+  over cost-acct lines, `profit = revenue − cost`. The **reversal** lands as the negation keyed
+  by its **own** internalId with `createdFromNetsuiteTransactionInternalId = the original`.
+
+### Timing / verification notes
+- The create webhook can lag **~20s** before the row appears (read-after-write / processing) —
+  wait before asserting.
+- On the debug webhook path there are **no** local app logs — confirm inbound arrival at the
+  ngrok inspector `http://127.0.0.1:4040/api/requests/http` (body is **base64**; decode before
+  grepping; buffer is ephemeral). See Gotchas.
+
+### Prod hygiene (critical — tests write to the single prod NetSuite account)
+All harnesses create **real** tiny (`$0`/`$0.01`) records in the **single prod NetSuite
+account (1095849)**. The legacy 5-min pull cron
+(`worker/crons/toga2/forecast2/import_sales.php`) can pull a briefly-alive test record into
+**prod** `Forecast.Sales` **independent of the webhook code**. After each test batch:
+1. Query the **prod reader** (`reader1.core.database.togahub.com`, `Forecast.Sales`) for the
+   test internalIds.
+2. **Guarded-DELETE exact matches** (customerId `2` / itemId `25` / revenue `±0.01`) via the
+   **prod writer**.
+Keep **create→delete windows short** so most records slip between cron runs; or pause
+`import_sales` during a batch. (The daily discrepancy-fix also cleans stragglers since the
+record is deleted in NetSuite.)
 
 ## Gotchas / known issues
 - **Testing locally pollutes PROD unless you UNDEPLOY the prod AMQ enqueuer first.** Each sale
@@ -287,6 +382,16 @@ Actions: `check | create | get | update | delete | sync | recent | amq | deploym
 - The cron's sign handling is not portable here — see Sign convention.
 
 ## Change history
+- 2026-06-26 — **Documented the full e2e testing playbook + harness inventory to run cold**
+  (6-step create→verify→update→verify→delete→verify lifecycle; per-type harness action sets;
+  the two execution modes — WEBHOOK vs LOCAL-ONLY `sync` — fixtures, expected signs, prod
+  hygiene). Added the read-only `test/@dave/test_fetchrecord_routes.php` probe. Recorded that
+  **`fetchRecord` moved from `_Component_Forecast_Db` to `_Component_Api_Netsuite`** (beside
+  `createRecord`; 7 callers reprefixed — SaleImport ×2, Opportunity ×3, SalesOrder ×2;
+  verify-the-class-before-relying). Added the **`git grep` caller-enumeration gotcha**: build
+  caller inventories for the shared NS helpers with `git grep -nF` per repo, not the fuzzy
+  search, which silently missed the production `SalesOrder.php` `createRecord` caller and caused
+  a reverted refactor. (dfranks)
 - 2026-06-26 — **Hardened + verified the full webhook path for all four sale types end-to-end**
   (create→insert, edit→update, delete→removeAll) with sign conventions reconfirmed (invoice/cashSale
   +, creditMemo/cashRefund −). Recorded durable gotchas: a UE enqueuer fires for a REST/M2M user only

package/knowledge/2.0/apps/_underscore/features/netsuite-rest-client.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-25
+updated: 2026-06-26
 owners: ["dfranks"]
 files:
   - _underscore/Component/Api/Netsuite/Netsuite.php
@@ -64,6 +64,24 @@ through `_ApiRequest` directly (mirroring `send()`'s auth/endpoint/header setup)
 > value carried in the thrown exception message (the lifecycle harness ships its own correct
 > `~`-delimited parse to sidestep this without editing the framework). Confirmed live 2026-06-26.
 
+### Read — `fetchRecord(string $route, string $label): array`
+
+A generic NS REST **GET + decode** primitive. **Moved here from `_Component_Forecast_Db`**
+(2026-06-26) so it sits beside `createRecord` with the other REST primitives — it is not
+Forecast-specific. Its **7 callers** were reprefixed to `_Component_Api_Netsuite::fetchRecord`:
+`SaleImport.php` ×2, `Opportunity.php` ×3, `SalesOrder.php` ×2 (static git-grep: zero stale
+`_Component_Forecast_Db::fetchRecord` refs; runtime-verified across all 5 SaleImport types +
+opportunity/employee/salesOrder routes via `test/@dave/test_fetchrecord_routes.php`).
+**Verify the class before relying on it** — it was just relocated.
+
+> **Enumerate callers of this class's shared helpers with `git grep`, not the fuzzy/agent
+> search.** When moving/renaming `createRecord` / `fetchRecord`, build the caller inventory with
+> `git grep -nF` **per repo** — the fuzzy search silently **missed**
+> `worker2/Worker/Netsuite/SalesOrder.php:925` (`createRecord`, the SalesOrder SOAP→REST
+> outbound push — a real **production** caller), producing a wrong "zero callers / test-only"
+> conclusion and a broken refactor that had to be reverted. Search case-insensitively for
+> `::method`, `function method`, and string/callable forms; confirm zero stale refs afterward.
+
 ### Update — reuse `send('PATCH', $route, $body)`
 
 Updates do **not** need a new helper. A NetSuite record PATCH returns 204 with no body, and
@@ -103,6 +121,12 @@ doc.)
 
 ## Change history
 
+- 2026-06-26 — **`fetchRecord` (generic NS REST GET + decode) moved onto this class** from
+  `_Component_Forecast_Db`, beside `createRecord`; 7 callers reprefixed (SaleImport ×2,
+  Opportunity ×3, SalesOrder ×2), git-grep clean + runtime-verified. Recorded the
+  caller-enumeration lesson: use `git grep -nF` per repo (not the fuzzy search, which missed the
+  production `SalesOrder.php` `createRecord` caller and caused a reverted refactor) when
+  moving/renaming these shared NS helpers. (dfranks)
 - 2026-06-25 — **Recorded a live bug in `createRecord()`'s trailing-id regex.** The pattern
   `'#/(\d+)(?:[?#]|$)#'` uses `#` as both the PCRE delimiter and a class member, so it always throws
   `Unknown modifier ']'` — *after* the record is created, breaking the outbound create/push path.

package/knowledge/INDEX.md

@@ -10,7 +10,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **togaview** (TOGa View) — 6 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 - **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
-- **test** (Test) — 11 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
+- **test** (Test) — 12 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 2 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
 - **tools** (Tools) — 5 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 

package/package.json

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