toga-ai 1.0.199 → 1.0.201

package/knowledge/1.0/apps/worker/features/forecast2-netsuite-reconciliation.md

@@ -68,6 +68,12 @@ by reconciling a chosen tranDate range directly against NetSuite.
     still go to stderr.
   - **`--verbose`** was trimmed — removed per-line MATCH/EXCLUDE/NOOP and the always-on per-SO summary;
     the per-SO header now prints lazily, once, only when the order has an INSERT/UPDATE/DELETE.
+  - **Step 4 per-statement SQL audit (added 2026-06-25).** The Step 4 results block now lists, one line
+    per statement, `<NetSuite SO internal id>  <SQL>` — the exact statement that **was run** (live) or
+    **would be run** (`--dry-run`), so you can audit a dry-run before applying or trace an unexpected
+    insert/update/delete back to its source order. Previously `emit()` executed-or-counted each write but
+    discarded the SQL string, leaving only aggregate counts. The listing inherits the existing `--quiet`
+    gating (prints only on a changed pass) and the `--dry-run` header wording ("would run" vs "applied").
 - `loop_trueup_open_orders.php [--prod] [--dry-run] [--verbose] [--quiet] [--sleep=N] [--days-back=N]`
   — continuous runner that recomputes a rolling `[today−N .. today]` window each pass and re-invokes
   `trueup_open_orders.php --by-lastmodified` until Ctrl-C. Uses `PHP_BINARY` + `passthru` with
@@ -113,6 +119,18 @@ by reconciling a chosen tranDate range directly against NetSuite.
   **classify a drift set as whole-missing vs. present-but-different**, and to scope a
   `Logs.Webhook`/`WorkerJobs` search window from the lastmodified timestamps.
 
+- **`trueup_open_orders` SQL-audit collector.** A global `$sqlLog` (alongside `$opCount`) collects
+  `['soid'=>.., 'sql'=>..]` for every write **in both live and dry-run modes**; `emit($sql, $db, $soId=null)`
+  records first, then executes only when not `--dry-run`. Every main-loop `emit()` passes the in-scope
+  NetSuite SO internal id (`$nsSoId`) — closed-order DELETE, both Classifications INSERT/UPDATE, the
+  OpenOrderItems UPDATE/INSERT, and the per-order DELETE flush. The Step 3b stale-cleanup DELETE is batched
+  by local row id across many SOs, so it keeps the default null `$soId` and is labelled `stale` (the full
+  stale SO id set is printed once above the listing). Each statement is whitespace-collapsed
+  (`preg_replace('/\s+/', ' ', trim(...))`) so multi-line built SQL renders on one line, and the listing is
+  appended to the existing `$resultLines` array (inheriting `--quiet` gating + `--dry-run` wording). Memory
+  stays bounded under the existing 1G `memory_limit`. (This corrected a prior docblock claim that `$sqls`
+  was never accumulated globally.)
+
 ## Data model
 
 `Forecast.Sales`, `Forecast.OpenOrderItems` on the **core2** cluster
@@ -253,6 +271,14 @@ None — Forecast2 is a single shared dataset.
 
 ## Change history
 
+- 2026-06-25 — **`trueup_open_orders` Step 4 now lists the exact per-statement SQL** (`<NS SO id>  <SQL>`,
+  one line per statement) for both live and `--dry-run` passes, so a dry-run is auditable and any
+  unexpected insert/update/delete is traceable to its source order. Implemented via a global `$sqlLog`
+  collector + `emit($sql,$db,$soId)` (records always, executes only when not dry-run); each main-loop emit
+  passes `$nsSoId`, and the batched Step 3b stale-cleanup DELETE is labelled `stale`. Inherits existing
+  `--quiet` gating and `--dry-run` wording; whitespace-collapsed to one line per statement. Corrects the
+  prior "`$sqls` never accumulated globally" docblock. `php -l` clean (PHP 7.2); not executed live/dry-run
+  this session. (dfranks)
 - 2026-06-25 — **`trueup_open_orders` gained `--by-lastmodified` / `--quiet` / leaner `--verbose`; added
   `loop_trueup_open_orders.php` as the stopgap for the real-time billed-order removal gap.**
   `--by-lastmodified` windows both Step 1 and Step 3b on `lastmodifieddate` (ET TIMESTAMP bounds) and

package/knowledge/INDEX.md

@@ -15,7 +15,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 14 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 15 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 15 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 6 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 2 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/knowledge/clients/rate/INDEX.md

@@ -3,6 +3,7 @@
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
 | [Rate Monthly Reconciliation Report](features/monthly-reconciliation-report.md) | 1.0 | A monthly cron that emails an Excel reconciliation report covering all Rate subscription sales orders and their linked PayPal payments for the prior calendar mo | worker/crons/notifications/reports/rate/send_monthly_rate_purchases_report.php, worker/schedules/cron.worker.notification.json |
+| [Rate SalesOrder → NetSuite CashSale Export (postPost)](features/netsuite-cashsale-export.md) | 2.0 | Rate sells home-warranty / home-tech-support products. | _underscore/Model/Rate/SalesOrder.php, _underscore/Model/Rate/Item.php |
 | [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](profile.md) | 2.0 | Rate is a mortgage/lending client. |  |

package/knowledge/clients/rate/features/netsuite-cashsale-export.md

@@ -0,0 +1,92 @@
+---
+title: "Rate SalesOrder → NetSuite CashSale Export (postPost)"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: rate
+type: client-feature
+status: active
+updated: 2026-06-25
+owners: ["rgirish"]
+files:
+  - _underscore/Model/Rate/SalesOrder.php
+  - _underscore/Model/Rate/Item.php
+related:
+  - 2.0/apps/_underscore/features/netsuite-rest-client.md
+  - clients/rate/profile.md
+---
+
+## Summary
+
+Rate sells home-warranty / home-tech-support products. When a Rate SalesOrder is created,
+the `_Model_Rate_SalesOrder::postPost` interceptor builds and writes a NetSuite **CashSale**
+(not a SalesOrder). This doc covers two pieces of that export added 2026-06-25: passing the
+order's ship-to (property) address onto the CashSale, and resolving each line item's NetSuite
+item internalId from a dedicated column with a partNumber fallback.
+
+This is Rate's override of the shared NetSuite write path documented in
+`2.0/apps/_underscore/features/netsuite-rest-client.md`.
+
+## Key files / entry points
+
+| File | Role |
+|---|---|
+| `_underscore/Model/Rate/SalesOrder.php` | `postPost` interceptor — builds the NetSuite CashSale (address + line items) |
+| `_underscore/Model/Rate/Item.php` | `_Model_Rate_Item` — declares `c_netsuiteInternalItemId` so the column is API-exposed and UI-settable |
+
+## How it works
+
+### Ship-to address → CashSale `shippingAddress`
+The `postPost` SQL query was expanded to `LEFT JOIN Addresses` (via
+`SalesOrders.shipToAddressId`) and `States`, selecting `line1`, `line2`, `city`, the
+state code, and `zip`. The address is captured from the first result row and set as a
+top-level `shippingAddress` on the CashSale — an `Address` object with `override=true`
+and `country='_unitedStates'`.
+
+This fires for **every** order that has a `shipToAddressId` set — it is **not** restricted
+to the Whole Home Warranty SKU (1429124), because `shippingAddress` is a top-level field on
+the CashSale, not a per-line concern. (The business driver was Whole Home Warranty orders
+needing the property address in NetSuite so ops / account teams can determine regional
+pricing, but the field applies to all orders.)
+
+### Line item NetSuite internalId resolution
+Each line item's NetSuite `RecordRef` internalId is now resolved as:
+
+1. `Items.c_netsuiteInternalItemId` when populated, else
+2. the hard-coded `partNumber` integer (1429122 / 1429123 / 1429124) as a fallback.
+
+The query was updated to `SELECT Items.c_netsuiteInternalItemId` alongside `partNumber`.
+The fallback exists because ops has not yet populated `c_netsuiteInternalItemId`.
+
+### `c_netsuiteInternalItemId` field declaration
+`Client_Rate.Items` has a `c_netsuiteInternalItemId INT` column that was not declared in the
+ORM. It is now declared as `FIELD_INTEGER` on `_Model_Rate_Item`, so the column is exposed
+through the API and can be set via the UI.
+
+## Production data state (as of 2026-06-25)
+
+- **All 39 Rate SalesOrders in `Client_Rate.SalesOrders` have `shipToAddressId = NULL`.**
+  The new code path only populates `shippingAddress` once the frontend starts setting
+  `shipToAddressId` on order creation. For the historical backfill export, the address was
+  pulled from the contact's `primaryContactAddressId → ContactAddresses → Addresses` join
+  instead — a one-off, not the going-forward path.
+- **`Items.c_netsuiteInternalItemId` is NULL for all three Rate SKUs** (partNumbers
+  1429122, 1429123, 1429124). Until ops populates it, the partNumber-integer fallback is the
+  active internalId path.
+
+## Gotchas / known issues
+
+- **`shippingAddress` only flows when `shipToAddressId` is set.** No live order has it set
+  yet (all 39 are NULL), so the new address path is effectively dormant until the frontend
+  populates the field on creation. Don't assume the CashSale carries an address from current
+  prod data.
+- **internalId fallback is partNumber, not the NS internalId.** Until ops backfills
+  `c_netsuiteInternalItemId`, CashSale lines reference the partNumber integer as the NS item
+  internalId. These happen to coincide for Rate today, but the clean path is the column.
+- **Historical backfill used a different address source** (contact primary address), not
+  `shipToAddressId` — do not confuse the one-off backfill join with the going-forward order
+  path.
+
+## Change history
+
+- 2026-06-25 — Added ship-to address (`LEFT JOIN Addresses`/`States`) to the CashSale as a top-level `shippingAddress` (override=true, US); resolved line-item NS internalId from `c_netsuiteInternalItemId` with partNumber fallback; declared `c_netsuiteInternalItemId` on `_Model_Rate_Item`. Confirmed all 39 prod orders have NULL `shipToAddressId` and all 3 SKUs have NULL `c_netsuiteInternalItemId` (rgirish)

package/knowledge/clients/rate/profile.md

@@ -10,12 +10,13 @@ project: SAML SSO Gateway
 client: rate
 type: profile
 status: active
-updated: 2026-06-24
+updated: 2026-06-25
 owners: ["rgirish", "bala"]
 files: []
 related:
   - clients/rate/features/saml-sso.md
   - clients/rate/features/monthly-reconciliation-report.md
+  - clients/rate/features/netsuite-cashsale-export.md
 ---
 
 ## Summary

package/package.json

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