toga-ai 1.0.218 → 1.0.220

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/verify_je_classification.php, test/@dave/probe_je_accounts.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,9 @@ 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/verify_je_classification.php
+  - test/@dave/probe_je_accounts.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 +75,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 +92,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
@@ -147,11 +169,25 @@ item-line upsert/reconcile machinery (`syncLines`/`guardedInsert`/`deleteRows`).
 - Lines hitting a **revenue** or **cost** GL account are grouped by **(salesRep, item)**:
   `revenue = Σ(credit − debit)` over revenue lines, `cost = Σ(debit − credit)` over cost
   lines, `profit = revenue − cost`.
-- **Account classification is done on the fly by NetSuite `accttype`** — SuiteQL
-  `SELECT id, accttype FROM account WHERE id IN (...)`, cached per run, bucketed via a tunable
-  `JE_ACCTTYPE_BUCKETS` map. It is **NOT** a hardcoded account-id list. PROVISIONAL default:
-  `Income → revenue`, `COGS → cost` (pending sales-team sign-off; open questions: whether
-  `OthIncome`/`Expense` count, and the Income-typed but "Cost"-named accounts 430/433).
+- **Account classification is an EXACT account-NUMBER allowlist** (sales-team-defined; this
+  *replaced* the old provisional `accttype`-bucket rule). Constants in
+  `_Component_Forecast_SaleImport`: `JE_REVENUE_ACCOUNT_NUMBERS = ['41100','41300','41500']`,
+  `JE_COST_ACCOUNT_NUMBERS = ['51100','51200']`. Any line whose account number is in neither
+  list is **ignored**. The helper `accountNumbers(accountIds)` (which **replaced**
+  `accountTypes()`) resolves each line account's `acctnumber` via SuiteQL
+  `SELECT id, acctnumber FROM account WHERE id IN (...)`, cached per run; matching is
+  **string membership of `acctnumber`**, not `accttype`.
+- **Sub-accounts are EXCLUDED by design — exact match, never prefix.** This chart of accounts
+  has real traps that both a `accttype` rule AND a prefix match would mis-bucket: under **41300**
+  "Service Revenue" sit `41300.01` (Service Revenue-Agent, `accttype` Income), `41300.02`/`.03`
+  (Service Cost-Agent, `accttype` **Bank**), and `41300.04` (Service **Costs**-Agent, `accttype`
+  **Income** despite the cost name); **51200** has `51200.01` (COGS Service-Agent). Exact-number
+  matching sidesteps all of them.
+- **Resolved account map** (number → internalId / name): `41100→245` Product Revenue,
+  `41300→339` Service Revenue, `41500→355` Pre-Sales Consulting; `51100→248` COGS Product,
+  `51200→249` COGS Service. Read-only resolver tool: `test/@dave/probe_je_accounts.php`.
+- **Likely future one-line tweak:** if the Agent sub-accounts should count, add `41300.01` to
+  the revenue list and `51200.01` to the cost list.
 - Group key uses `json_encode([salesRep, item])` (not a string-join) to stay collision-safe
   once the fields go live — an empty-string separator would let `"5|" + null` collide.
 
@@ -218,28 +254,116 @@ 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`).
+
+> **Scope of the update step (what it does and does NOT cover):** the update step changes
+> **only `tranDate`** — a tracked column, so it forces a real change-detection UPDATE while
+> the amount stays unchanged. It does **NOT** exercise updates to revenue / customer /
+> salesRep / item, nor line add/remove. A future tester verifying those must extend the
+> harness; the current update-step assertion only proves the tracked-column UPDATE path.
+
+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, acctnumber **41100**),
+  **248** (COGS Product, **51100**), **215** (Clearing - CSS — ignored, neither revenue nor
+  cost); set a `reversalDate` so NetSuite auto-creates the reversal. Classification is now by
+  **account number** (allowlist), so any clearing/balance line lands outside both lists and is
+  ignored automatically.
+- **Discriminating classification test — `test/@dave/verify_je_classification.php`:** posts one
+  balanced JE `+10/+20/+30` to `41100/41300/41500`, `−5/−7` to `51100/51200`, **plus `+100` to
+  the excluded sub-account `41300.01`**, plus a clearing balance line → local `Forecast.Sales`
+  aggregates to **revenue=60.00, profit=48.00** (NOT 160 — proving `41300.01` is excluded and the
+  exact-number rule is in force).
+
+### 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 +411,29 @@ 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 — **Changed JE revenue/cost classification from `accttype` buckets to an EXACT
+  account-NUMBER allowlist** (sales-team-defined): `JE_REVENUE_ACCOUNT_NUMBERS =
+  {41100,41300,41500}`, `JE_COST_ACCOUNT_NUMBERS = {51100,51200}`; everything else ignored.
+  `accountNumbers()` (replaced `accountTypes()`) resolves each account's `acctnumber` via
+  SuiteQL, cached per run; match is exact-string, **never prefix** — sub-accounts are excluded
+  by design to dodge real chart-of-accounts traps (`41300.04` "Service Costs-Agent" is
+  `accttype` Income; `41300.02/.03` are `accttype` Bank). Resolved map: 41100→245, 41300→339,
+  41500→355, 51100→248, 51200→249. Verified with a discriminating balanced-JE test
+  (`test/@dave/verify_je_classification.php` → revenue=60.00/profit=48.00, proving `41300.01`
+  excluded); read-only resolver `test/@dave/probe_je_accounts.php`. Future one-liner: add
+  `41300.01`/`51200.01` if Agent sub-accounts should count. Also clarified the e2e harness
+  update step exercises **only `tranDate`** (a tracked column) — not revenue/customer/salesRep/
+  item or line add/remove. (dfranks)
+- 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/package.json

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