toga-ai 1.0.98 → 1.0.100

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

@@ -5,3 +5,4 @@
 | [Worker (1.0 Framework) Architecture](architecture.md) | `worker` is the legacy (**1.0** `App_` framework) **background-job tier**. | worker/index.php, worker/_/app/framework.php, worker/crons/, worker/schedules/, worker/ebs/cron.worker.php, worker/.ebextensions/035_cron.worker.config |
 | [Forecast2 ↔ NetSuite Reconciliation & Trueup Tooling](features/forecast2-netsuite-reconciliation.md) | CLI tools to **audit** and **repair** drift between the production `Forecast` DB (core2) and NetSuite. | test/@dave/reconcile_netsuite_totals.php, test/@dave/analyze_netsuite_forecast_diff.php, test/@dave/trueup_sales.php, test/@dave/trueup_open_orders.php, test/@dave/trueup_opportunities.php, test/@dave/probe_sales_gap_direct.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [Prudential: Send Shipments for the Day report (daily cron)](features/send-shipments-for-the-day.md) | Daily cron (9:00 PM) that emails Prudential and Dell stakeholders an Excel report of all devices shipped that day, including tracking number, serial number, emp | worker/crons/notifications/reports/send_shipments_for_the_day.php |
+| [Onboarding a Client to the NetSuite TOGa Supply Sync](workflows/onboarding-client-to-netsuite-togasupply-sync.md) | How to add a new TOGa 2 client to the per-client NetSuite → TOGa Supply importer (`worker/crons/toga2/netsuite/`). | worker/crons/toga2/netsuite/sync_togasupply.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql |

package/knowledge/1.0/apps/worker/workflows/onboarding-client-to-netsuite-togasupply-sync.md

@@ -0,0 +1,116 @@
+---
+title: Onboarding a Client to the NetSuite TOGa Supply Sync
+framework: "1.0"
+repo: worker
+project: Worker
+client: shared
+type: workflow
+status: active
+updated: 2026-06-16
+owners: ["dfranks"]
+files:
+  - worker/crons/toga2/netsuite/sync_togasupply.php
+  - worker/crons/toga2/netsuite/common_sync_togasupply.php
+  - worker/schedules/cron.worker.sync.json
+  - dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql
+related: []
+---
+
+## Summary
+How to add a new TOGa 2 client to the per-client NetSuite → TOGa Supply importer
+(`worker/crons/toga2/netsuite/`). Each client gets a thin wrapper cron that sets its
+`CLIENT_CONFIGURATION` + `IS_ENABLED_*` flags and then `require_once`s the shared
+`common_sync_togasupply.php`, which builds all lookups and runs the 6 sync sections
+(Sales Orders, Purchase Orders, Invoices, Item Receipts, Item Fulfillments, Inventory
+Adjustments). Reads come from production NetSuite (REST/SuiteQL); writes go to the TOGa2
+API (`App_Api_Toga2::send`), which lands in that client's `Client_<Name>` database.
+
+## Steps
+1. **Create the wrapper** `worker/crons/toga2/netsuite/sync_togasupply_<client>.php`,
+   modeled exactly on an existing one (e.g. `sync_togasupply_compass_usa.php`). Set
+   `CLIENT_CONFIGURATION` (`client`, `isParentCustomer`, `api`, `secret`,
+   `importCustomerPurchaseOrdersOnVendor`) and the constants. Shared constants are the same
+   across clients: `NETSUITE_CUSTOM_FIELD_ID__END_USER_CUSTOMER = 3149`,
+   `SHIPPING_LOCATION_TYPE_UUID = 527a3995-…`, `WAREHOUSE_LOCATION_TYPE_UUID = 78c24f51-…`,
+   and `importCustomerPurchaseOrdersOnVendor = 10ed18ec-0999-53d9-f9db-5892d90f09d4`.
+   Get `client` from `Core.Clients` (by name); get `api`/`secret` from
+   `Client_<Name>.Apis`. Lint with `C:\xampp7\php\php.exe -l` (prod is PHP 7.2).
+2. **Determine `isParentCustomer` by probing NetSuite — do not assume.** It controls whether
+   the common body calls `listChildCustomers()` (parent) or `fetchCustomerById()` (flat).
+   `listChildCustomers(N)` runs `SELECT id FROM customer WHERE parent = N`. If the client's
+   NetSuite customer has **zero children**, `isParentCustomer` MUST be `false`, or the sync
+   builds an empty customer list, registers nothing, and imports nothing (silent no-op). See
+   Gotchas.
+3. **Seed the Parameters table** (see the dedicated section below) — REQUIRED or the sync
+   aborts on its first parameter read.
+4. **Add the schedule entry** in `worker/schedules/cron.worker.sync.json`: all
+   `sync_togasupply_*` jobs run `*/5 * * * *`, `active: 1`. The cron only runs once a
+   schedule entry references the file and the worker is redeployed.
+5. **Deploy order matters:** the Parameters seed must hit prod `Client_<Name>` **before or
+   with** the cron going live, or the sync 404-aborts (and throws a Sentry error) every 5
+   minutes.
+
+## Parameters seed (the required, easily-missed step)
+The sync reads/writes per-client sync state via the TOGa2 API `/parameters` endpoint, which
+is **update-only** — a `GET`/`PUT` on a non-existent key returns `404 EV-6`, and because
+`App_Api_Toga2::send()` defaults `$throwExceptionOnApiError = true`, that 404 **throws and
+aborts the entire run** before any record is processed. The `startModeIteration()` ternary
+(`isSuccess ? value : MIN_DATETIME`) looks like it tolerates a missing key, but it never
+gets there because `send()` throws first. Every live client (e.g. Compass) was seeded at
+onboarding; a new client has none.
+
+The `Parameters` *table* already exists in every `Client_<Name>` DB — you only seed **rows**.
+Add a `dbchanges2/Client_<Name>/<date> - NetsuiteSyncParameters.sql` migration modeled on
+`dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql`, inserting all **12** keys:
+- 6 × `NETSUITE_LAST_SYNC_DATETIME_{SALES_ORDERS,PURCHASE_ORDERS,INVOICES,ITEM_RECEIPTS,ITEM_FULFILLMENTS,INVENTORY_ADJUSTMENTS}`
+  → a start datetime. This sets how far back the initial backfill pulls (5-day windows, every
+  5 min). Pick deliberately: `2018-01-01` = full history; a recent date = go-forward only.
+- 6 × `NETSUITE_EXECUTION_MODE_*` → `864000-IDLE` (the interval is clamped to
+  `MAX_TIME_WINDOW_TO_FETCH_FROM_NETSUITE_SECONDS = 432000` on first run, so the exact
+  seed interval is not critical; `IDLE` is what matters).
+
+Use `(UUID(), '<key>', '<value>')` rows — `Parameters.uuid` is required and unique.
+dbchanges2 files use the unqualified `Parameters` table name (deployer selects the DB from
+the directory; no `USE`).
+
+## Systems involved
+- `worker` cron tier (1.0) — the wrapper + `common_sync_togasupply.php`.
+- Production NetSuite (account `1095849`) via `App_Api_Netsuite_Rest` (SuiteQL/REST) — reads.
+- TOGa2 API (`App_Api_Toga2`) — writes to `Client_<Name>` (+ logs to `Logs_<Name>`).
+- `dbchanges2/Client_<Name>/` — the Parameters seed migration.
+
+## Local testing
+- The worker's `[api] _` and api2's `[database]/[databaseClient]/[database1]` on the dev
+  laptop point at local (`http://api2/v2` → local Apache/api2 → localhost MySQL). NetSuite is
+  the **production** account but reads are read-only.
+- A local end-to-end run needs the client's schemas present locally: import both
+  `Client_<Name>` AND `Logs_<Name>` from the read replicas (client2 / logs clusters) into
+  local XAMPP. `Logs_<Name>` only needs the **schema** (`mysqldump --no-data`) — its API-log
+  history can be many GB; api2 connects to it (link `ClientLogs`) on every request and 500s
+  with "Unknown database 'logs_<name>'" if absent.
+- Run the cron in place with `C:\xampp8\php\php.exe` from the `worker/` dir; the autoloader
+  walks up to `worker/_` for `__APPROOT__`. `App_Api_Netsuite_Rest::authenticate()` +
+  `App_ApiTransaction->setLogging(false)` is the laptop-safe NetSuite pattern (see
+  `test/@dave/nsq.php`, a read-only SuiteQL runner).
+- Verified behavior: empty window → 0 writes, checkpoint advances (clean no-op); record
+  already present → `PUT` update (idempotent, keyed on `c_netsuiteInternalSalesOrderId`, no
+  dupes); record absent → `POST` insert. Checkpoints (`NETSUITE_LAST_SYNC_DATETIME_*`)
+  advance by one window and `NETSUITE_EXECUTION_MODE_*` flips back to `…-IDLE` when a section
+  finishes cleanly.
+
+## Edge cases & escalation
+- **`isParentCustomer` wrong** → silent no-op (true on a childless customer) or missed
+  end-user matching. Always probe NetSuite first.
+- **Parameters not seeded in prod** → sync throws every 5 min; surfaces as a `worker1` Sentry
+  error and zero imports.
+- **Missing catalog item** on an incoming order may throw mid-run depending on the section;
+  the checkpoint does not advance past a throwing window, so it self-heals once the dependency
+  exists.
+
+## Change history
+- 2026-06-16 — Documented the onboarding process after adding Quad (TRUE-79575): wrapper +
+  schedule + the required 12-key Parameters seed; captured the `isParentCustomer` NetSuite
+  probe and the local Client_/Logs_ schema requirement. (dfranks)
+
+## Related docs
+- [Forecast2 NetSuite reconciliation](../features/forecast2-netsuite-reconciliation.md)

package/knowledge/INDEX.md

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 4 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 4 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 5 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **togadesk** (TOGa Desk) — 7 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 5 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)

package/knowledge/clients/compass-usa/INDEX.md

@@ -2,7 +2,7 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
-| [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF) on the upstream SalesOrder. | _underscore/Model/Compass/AdvanceShippingNotice.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql, dbchanges2/Client_Compass/2026-06-15b - BackfillSA132781ItemFulfillmentTracking.sql |
+| [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF) on the upstream SalesOrder. | _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Model/Compass/PurchaseOrder.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql, dbchanges2/Client_Compass/2026-06-15b - BackfillSA132781ItemFulfillmentTracking.sql, dbchanges2/Client_Compass/2026-06-16 - CleanupSA132763CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16b - CleanupSA132743CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16c - BackfillSA132763C40QYUCTracking.sql |
 | [Compass: Item-Fulfillment TableViews (for-sales-order-items & for-sales-orders, tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | Two sibling Compass TableViews in `Client_Compass` display fulfilled items in toga2-supply, both driven by `TableViews` / `TableViewJoins` / `TableViewFields` c | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql, dbchanges2/Client_Compass/2026-06-11 - ItemFulfillmentsForSalesOrdersTableView.sql, dbchanges2/Client_Compass/2026-06-15a - FixItemFulfillmentTrackingNumberJoins.sql |
 | [Compass MITS PO → SO Item Linking](features/mits-po-to-so-item-linking.md) | 2.0 | MITS sends Compass inbound Purchase Orders (`POST /v2/purchase-orders`) against a Sales Order (`mitsSalesOrder`). | _underscore/Model/Compass/PurchaseOrder.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |

package/knowledge/clients/compass-usa/features/asn-to-item-fulfillment.md

@@ -5,13 +5,17 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-06-15
+updated: 2026-06-16
 owners: [jcardinal]
 files:
   - _underscore/Model/Compass/AdvanceShippingNotice.php
+  - _underscore/Model/Compass/PurchaseOrder.php
   - api2/Component/Api/Cxml/Cxml.php
   - dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql
   - dbchanges2/Client_Compass/2026-06-15b - BackfillSA132781ItemFulfillmentTracking.sql
+  - dbchanges2/Client_Compass/2026-06-16 - CleanupSA132763CrossLineTracking.sql
+  - dbchanges2/Client_Compass/2026-06-16b - CleanupSA132743CrossLineTracking.sql
+  - dbchanges2/Client_Compass/2026-06-16c - BackfillSA132763C40QYUCTracking.sql
 related:
   - ../../../2.0/apps/_underscore/features/recursive-item-fulfillments.md
 ---
@@ -143,9 +147,43 @@ Compass Canada (`Model/Compass/Canada/`) is a separate sub-client. The Compass c
   number) straight into queries. These are now passed through `_Database::escape()`.
 - Separate latent bug in the 1.0 worker: the Strategic Systems cron's no-serials branch
   builds `$itemLevelTrackingNumbers` but never attaches it to the ASN payload.
+- **Cross-line tracking contamination from bad SOI↔POI bridge rows (root cause, fixed
+  forward 2026-06-11):** `postPost` resolves which IFI(s) a tracking number attaches to by
+  joining `AdvanceShippingNoticeItems → SalesOrderItems_PurchaseOrderItems → SalesOrderItems`.
+  It trusts that bridge completely, so a wrong bridge row silently sends one ASN's tracking
+  onto an unrelated part's IFI. Two distinct pre-fix bugs produced bad bridge rows on Compass
+  SA orders: (1) `_Model_Compass_PurchaseOrder` linked SO↔PO items by matching
+  `SalesOrderItems.lineNumber = PurchaseOrderItems.lineNumber` — but a PO item's lineNumber is
+  **PO-local** (each PO starts at 1), so when one SO is split across multiple POs the PO line
+  numbers collide with unrelated SO lines (e.g. SA132743: PO `50305071-1` line 1 = 910-006272
+  wrongly linked to SO line 1 = C40QYUC). Fixed in `_underscore` commit `ec935478` (2026-06-11,
+  "Only link SO/PO items for MR orders") — the lineNumber join is now MR-only; SA orders link
+  via `createdFromSalesOrderItem` (item identity). (2) The 1.0 worker cron
+  `3a_import_office_depot_purchase_orders.php` paired API-returned PO items to SOIs by array
+  index, producing off-by-one neighbor links (fixed forward to pair by lineNumber; see
+  SA132763 cleanup file header). **Diagnosing:** a bridge row is provably wrong when its
+  `SalesOrderItems.itemId <> VendorItems.itemId` (the linked SOI's product differs from the PO
+  item's actual product). The `2026-06-16*` cleanup migrations delete exactly those rows plus
+  the tracking they spilled, scoped to one order.
+- **Retroactive cleanup MUST be paired with a backfill — a cleanup-only repair leaves the
+  line blank.** Removing the *wrong* tracking from a contaminated IFI does not restore the
+  *correct* one: the correct number often never reached the IF side (the SO was fulfilled
+  out-of-band before the 2026-06-15 reconcile fix, and the cleanup adds nothing). The original
+  `2026-06-16 - CleanupSA132763CrossLineTracking.sql` was cleanup-only and left C40QYUC on
+  SA132763 with no tracking at all; `2026-06-16c` backfilled it. When repairing an order, also
+  backfill each affected IFI's correct tracking (the tn carried by an ASN item whose
+  `VendorItems.itemId` matches the IFI's SOI item) at both item and package level, guarded by
+  `NOT EXISTS`. ~116 PO items across other Compass orders share the off-by-one fingerprint and
+  are not yet repaired — a broader reviewed backfill is still outstanding.
 
 ## Change history
 Dated one-liners, newest first.
+- 2026-06-16 — Identified cross-line tracking contamination root cause: bad
+  `SalesOrderItems_PurchaseOrderItems` rows (PO-local lineNumber collision in
+  `_Model_Compass_PurchaseOrder`, fixed forward 2026-06-11 `ec935478`; and the worker ODP-PO
+  cron's array-index pairing). Repaired SA132743 (`2026-06-16b`, cleanup + backfill) and
+  backfilled SA132763's C40QYUC (`2026-06-16c`) after finding the `2026-06-16` SA132763 cleanup
+  was cleanup-only and left the line blank. (jcardinal)
 - 2026-06-15 — `postPost` + helpers refactored so **UUID is the reference field**, dropping all
   reliance on the integer `id` returned from `internalApiRequest` (not always present). Helper
   returns are uuid-only; `$trackingTargets`/`$packageTrackingByItemFulfillment` are uuid-keyed;

package/package.json

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