toga-ai 1.0.243 → 1.0.244

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

@@ -35,6 +35,7 @@ related:
   - ../architecture.md
   - ../../worker2/architecture.md
   - ../../worker2/features/netsuite-salesorder-open-orders-sync.md
+  - ../../worker2/features/netsuite-supporting-record-webhook-importer.md
   - ./netsuite-rest-client.md
 ---
 

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

@@ -15,6 +15,7 @@
 | [Monitoring Framework (Orchestrator + Child Monitors)](features/monitoring-framework.md) | A unified, DB-driven monitoring framework for business-critical data flows (Compass POs, Prudential asset imports, AIG closed claims, …). | worker2/Worker/Monitor.php, worker2/Worker/Monitors/, worker2/Worker/Monitors/RateEntitlement.php, worker2/Worker/Notification/Email.php, worker2/Worker/Rate.php, dbchanges2/Core/2026-05-21 - Monitors.sql, dbchanges2/Core/2026-06-29a - Rate Entitlement Contract Monitor.sql |
 | [NetSuite → TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, test/@dave/probe_clickup_desc_match.php, test/@dave/test_model_load_behavior.php, dbchanges2/Forecast/2026-06-25a - Add unique index on Opportunities netsuiteOpportunityInternalId.sql, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)](features/netsuite-salesorder-open-orders-sync.md) | Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). | worker2/Worker/Netsuite/SalesOrder.php, worker2/Worker/Netsuite.php, test/@dave/probe_salesorder_rest_shape.php, test/@dave/probe_open_order_lines.php, test/@dave/check_so_status.php, test/@dave/check_so_history.php, test/@dave/probe_so_rest_lines.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_open_order_gating.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
+| [NetSuite Supporting-Record Webhook Importer (the reusable recipe)](features/netsuite-supporting-record-webhook-importer.md) | A single **repeatable recipe** for porting a legacy daily-pull NetSuite *supporting-record* importer (the lookup/dimension tables behind Forecast2 — Employees, | worker2/Worker/Netsuite/Employee.php, worker2/Worker/Netsuite/Account.php, worker2/Worker/Netsuite/Classification.php, worker2/Worker/Netsuite/Customer.php, worker2/Worker/Netsuite/Item.php, worker2/Worker/Netsuite.php, _underscore/Model/Forecast/Employee.php, _underscore/Model/Forecast/Account.php, _underscore/Model/Forecast/Classification.php, _underscore/Component/Forecast/Db/Db.php, test/@dave/test_employee_lifecycle.php, test/@dave/test_account_lifecycle.php, test/@dave/test_classification_lifecycle.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, worker/crons/toga2/forecast2/import_supporting_records.php |
 | [DB-Driven Notification (Internal) Email](features/notification-email.md) | Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated, not client-facing transactional mail) are sent through one worker | worker2/Worker/Notification/Email.php, _underscore/Model/Client/EmailTemplate.php, dbchanges2/Client/2026-06-23a - EmailTemplateWrapper.sql, dbchanges2/Client_True/2026-06-23a - EmailTemplateWrapper.sql |
 | [Startech Webhook Handler (worker2)](features/startech-webhook-handler.md) | Receives inbound webhook events from Startech (Easeedesk) and creates or updates the corresponding ticket in TOGA 2.0. | worker2/Worker/Startech.php |
 | [Talos (TOGa IQ) Meeting-Notes Integration & Token Auto-Refresh (consumer)](features/talos-meeting-notes-integration.md) | How a **dev tool / agent consumes Talos (TOGa IQ)** to query the team meeting-notes corpus programmatically. | .claude/skills/plan-ticket/scripts/talos.js |

package/knowledge/2.0/apps/worker2/features/netsuite-supporting-record-webhook-importer.md

@@ -0,0 +1,135 @@
+---
+title: NetSuite Supporting-Record Webhook Importer (the reusable recipe)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-30
+owners: ["dfranks"]
+files:
+  - worker2/Worker/Netsuite/Employee.php
+  - worker2/Worker/Netsuite/Account.php
+  - worker2/Worker/Netsuite/Classification.php
+  - worker2/Worker/Netsuite/Customer.php
+  - worker2/Worker/Netsuite/Item.php
+  - worker2/Worker/Netsuite.php
+  - _underscore/Model/Forecast/Employee.php
+  - _underscore/Model/Forecast/Account.php
+  - _underscore/Model/Forecast/Classification.php
+  - _underscore/Component/Forecast/Db/Db.php
+  - test/@dave/test_employee_lifecycle.php
+  - test/@dave/test_account_lifecycle.php
+  - test/@dave/test_classification_lifecycle.php
+  - test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js
+  - worker/crons/toga2/forecast2/import_supporting_records.php
+related:
+  - ./netsuite-opportunity-sync.md
+  - ./netsuite-salesorder-open-orders-sync.md
+  - ../../_underscore/features/forecast-sale-import.md
+  - ../../_underscore/features/netsuite-rest-client.md
+  - ../architecture.md
+---
+
+## Summary
+
+A single **repeatable recipe** for porting a legacy daily-pull NetSuite *supporting-record*
+importer (the lookup/dimension tables behind Forecast2 — Employees, Accounts, Classifications,
+Customers, Items) into a **real-time, webhook-driven, single-record upsert**. A NetSuite
+create/edit/delete arrives at `webhook.togahub.com/netsuite`, the `_Worker_NetSuite::Webhook`
+router dispatches `Netsuite/<Record>/<verb>`, and a thin per-record handler upserts (or
+guarded-deletes) one row in the `Forecast` schema.
+
+This is the supporting-record sibling of the transaction-family importers — the
+[Opportunity sync](./netsuite-opportunity-sync.md) (header+children), the
+[Open-Orders sync](./netsuite-salesorder-open-orders-sync.md), and the
+[Forecast.Sales import engine](../../_underscore/features/forecast-sale-import.md). After
+Items + Customers established it and Employees/Accounts/Classifications repeated it verbatim, the
+**recipe is the durable knowledge**: the remaining siblings are mechanical. This doc captures the
+recipe and its two recurring variants so a new one is a fill-in-the-blanks job, not a fresh design.
+
+## The recipe (per supporting record)
+
+1. **Handler** `worker2/Worker/Netsuite/<Record>.php`:
+   `abstract class _Worker_Netsuite_<Record> implements _Interface_Static_Webhook_Netsuite`.
+   The shared `_Worker_NetSuite::Webhook` router PascalCases the inbound `recordType` to find it —
+   **no router edit is needed.** Verbs:
+   - `post` / `put` → `syncRecord()` then `_Database::transactionCommit(self::DB_FORECAST)`
+     (the lazy-transaction discipline — `syncRecord` itself never commits; the caller owns the txn).
+   - `delete` → run the **referenced-guard** first, and commit **only if it actually deletes**.
+2. **`syncRecord()`** (no commit): fetch the record via SuiteQL single-id form —
+   `_Component_Api_Netsuite::send('POST', QUERY_SUITEQL.'?limit=1', ['q'=>$sql], ['Prefer'=>'transient'])`
+   — then **upsert keyed on `netsuiteInternalId`**: `load()` the existing row, then **change-detect
+   with string-cast compares** (`_Number::nullableIntChanged` for nullable ints) before `save()`.
+   The guard is mandatory because **`save()` does NOT diff** — without the change-detect it would
+   re-write (and could re-touch) every field on every webhook.
+3. **Model** `_underscore/Model/Forecast/<Record>.php extends _Model_True`, declaring **ONLY the
+   NetSuite-sourced columns.** Deliberately **omit externally-managed columns** so a webhook upsert's
+   `save()` can never null them — e.g. Employees' `teamId` / `departmentId` / `role` / `urlHeadshot`
+   are Power-BI/HR-managed and are left off the model.
+4. **Delete guard** = a `_Component_Forecast_Db::<record>IsReferenced(int): bool` helper using
+   `SELECT EXISTS( … UNION ALL … )` across **every inbound RESTRICT FK**. Referenced → return a
+   *retained-message string* (do **NOT** throw, do **NOT** blast dependent rows); unreferenced →
+   hard-delete. All these helpers are added to the **same** `_underscore/Component/Forecast/Db/Db.php`
+   right after `lookupId()` (so independent sibling-ticket PRs branched from `_production` conflict
+   *trivially* on merge — keep every helper method).
+5. **Enqueuer:** add `'<record>':'<record>'` to `RECORD_TYPE_MAP` in
+   `test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js` (account/customer/employee/
+   classification entries already exist).
+6. **e2e harness** `test/@dave/test_<record>_lifecycle.php`: clone an existing one. It drives NetSuite
+   REST (check/create/get/update/delete) + the in-process worker verbs (post/put/verb-delete) + a local
+   dump of the resulting `Forecast` rows. Boots via chdir `worker2` + `require index.php`.
+7. **Cron:** leave the legacy `SHOULD_SYNC_<X>` daily pull **ON** as a backstop (and, for self-ref
+   records, the parent/supervisor backfill). It shares `import_supporting_records.php` with the other
+   sections, so **never disable the wrapper.**
+
+## Two recurring variants
+
+- **Self-referential parent/supervisor FK** (`Employees.supervisorEmployeeId`,
+  `Classifications.parentClassificationId`) = **RESOLVE-OR-NULL, never recursive upsert.** Resolve the
+  parent's local id by its NetSuite internalId via `lookupId`; if absent store **NULL** (the daily cron
+  backfills the link later). Inserting a non-existent local parent id would violate or dangle the FK.
+  The delete guard for a self-ref record must **also** check for child rows
+  (`WHERE parent…Id = id`) to avoid orphaning the hierarchy.
+- **Type/enum mapping** (Accounts): replicate the authoritative shim's `accttype`→canonical map
+  (`App_Api_Netsuite_Rest::listAccounts`, `library/app/api/netsuite/rest.php:218-237`) as a handler
+  const `ACCT_TYPE_MAP` so stored values stay format-consistent (`_income`, `_accountsReceivable`, …);
+  an unmapped value passes through raw. **Keep the const in sync with the shim.**
+- **Name from a hierarchical NetSuite `name`/`fullname`** = the **leaf segment**
+  (`explode(' : ')` + `array_pop`), matching the SOAP/cron/Item resolver.
+
+## Gotchas / known issues
+
+- **SuiteQL over the REST client has NO server-side placeholder binding.** `_Component_Api_Netsuite::send`
+  passes the query string as-is, so the **`(int)` cast on an already-int id is the injection control** —
+  the same codebase-wide idiom used by `lookupId()` and the Item/Opportunity/Employee handlers. A
+  php-reviewer flags it **CRITICAL** on a fresh read; it is **acceptable here** because the id is a
+  local PK from `load()`, never user input. Document the cast-only mitigation with a one-line comment.
+- **SuiteQL returns parent/supervisor reference ids as numeric STRINGS**, so the private resolve-helper
+  parameter must stay **untyped** (not `int|null`) or it `TypeError`s.
+- **The supporting-record tables already carry a UNIQUE index on `netsuiteInternalId`** (Employees,
+  Accounts, Classifications, Customers, Items), so the upsert's `load()` resolves exactly one row — no
+  duplicate-amplification (unlike the [opportunity `load()` footgun](./netsuite-opportunity-sync.md)),
+  no migration needed.
+- **`save()` does not diff** — see recipe step 2: the change-detect guard before `save()` is what makes
+  a no-change webhook a true no-op.
+
+## Change history
+
+- 2026-06-30 — Captured the supporting-record webhook-importer recipe and its two variants
+  (self-ref RESOLVE-OR-NULL parent FK + child-orphan delete-guard; Accounts `accttype` enum map; leaf
+  segment naming) after the third+ application (TRUE-79870 Employees, TRUE-79871 Accounts, TRUE-79872
+  Classifications) repeated the Items/Customers pattern verbatim. Recorded the model-omits-externally-
+  managed-columns rule, the `_Component_Forecast_Db::<record>IsReferenced` delete-guard contract
+  (retained-message string, never throw/blast), the trusted-int SuiteQL idiom (no REST placeholder
+  binding; cast-only mitigation), the SuiteQL-returns-string reference-id `TypeError` trap, and the
+  leave-the-legacy-cron-on-as-backstop boundary. (dfranks)
+
+## Related docs
+
+- [NetSuite → TOGA Opportunity Sync](./netsuite-opportunity-sync.md) — header+children transaction sibling.
+- [NetSuite → Forecast Open-Orders Sync](./netsuite-salesorder-open-orders-sync.md).
+- [Forecast.Sales NetSuite import engine](../../_underscore/features/forecast-sale-import.md) — the
+  revenue-transaction family + the shared `_Component_Forecast_Db` low-level helpers.
+- [Worker (worker2) Architecture](../architecture.md).

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)_ — 19 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 22 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 23 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 7 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)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

package/package.json

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