toga-ai 1.0.563 → 1.0.565

package/knowledge/1.0/apps/library/features/netsuite-item-isfulfillable-sync.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-07-28
+updated: 2026-08-12
 owners: [bala]
 files:
   - library/app/netsuite.php
@@ -18,6 +18,7 @@ related:
   - ../../worker/features/netsuite-togasupply-per-client-sync.md
   - ../../worker/workflows/isfulfillable-multi-client-backfill.md
   - ../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md
+  - ../../../clients/compass-usa/features/isfulfillable-data-quality-and-type-rule.md
 ---
 
 ## Summary
@@ -85,9 +86,27 @@ physical goods from services — `itemtype` would, but the sync has never used `
 `isSerialized`), so this feature intentionally reflects NetSuite's flag **as-is**. **Net effect:
 nearly everything resolves to `fulfillable = 1`.**
 
-- **Open product decision (caveat):** because services come back fulfillable, the storefront makes
-  everything clickable. Whether that is intended vs. needing `itemtype` to hide services is
-  **pending product confirmation**.
+- **Open product decision (RESOLVED for Compass, 2026-08-12):** because services come back
+  fulfillable, the storefront makes everything clickable. A prod evidence review found that
+  `itemtype` **cannot confirm** fulfillability (physical types like DESKTOPS show 0% tracked) but a
+  **tracking ride-along test** cleanly disqualifies fee/software/miscellaneous lines. Compass adopted
+  a **type-derived override** of NetSuite's value — see
+  [Compass isFulfillable data quality & type rule](../../../clients/compass-usa/features/isfulfillable-data-quality-and-type-rule.md).
+  Read the write-time-guard gotcha below before implementing it anywhere.
+
+## ⚠ CRITICAL — the existing-item refresh REVERTS any local override
+`getCreateItem`'s refresh (added 2026-07-28) rewrites `isFulfillable` on **existing** items whenever
+NetSuite's value differs from the stored value. NetSuite returns **`T` for service (`NonInvtPart`)
+items**, so **any locally-derived `0` is flipped back to `1` on the next sync run**. A data migration
+alone cannot hold an override — it silently reverts within a day.
+
+Proven from the prod audit log: Compass items **2382 / 2384 / 2385** (`US-IOS-SSC-SHR`,
+`US-IOS-VENUENEXT`, `US-IOS-VIRTUALMGR` — itemType `SERVICES`, assetType `CONSULTING`) were stamped
+**NULL → 1 on 2026-08-04 13:56:00-01** by `apiId 1`, `userId NULL`, inside a 1–2 items/second cron
+sweep that started 13:45 and set every item to `1`.
+
+**Rule: any policy that overrides NetSuite's flag must be enforced at WRITE TIME** — a
+`prePut`/`prePost` guard on Items in `_Model_Client_Item` — **in addition to** the backfill.
 
 ## Verification performed
 - **Prod read-only dry-run:** 20 reachable Compass items; chain walk correct
@@ -106,6 +125,13 @@ nearly everything resolves to `fulfillable = 1`.**
   in `Client_Compass.Apis` (name `Agilant`) — never reproduce the secret value.
 
 ## Change history
+- 2026-08-12 — Prod investigation (no code change): recorded that the **existing-item refresh
+  reverts any local override** (NetSuite returns `T` for services; audit-log proof on Compass items
+  2382/2384/2385, stamped NULL→1 on 2026-08-04), so an override must be enforced by a write-time
+  `prePut`/`prePost` guard, not a migration. Closed the long-standing **open product decision** for
+  Compass — item type cannot *confirm* fulfillability, but the tracking ride-along test disqualifies
+  fee/software/miscellaneous lines; Compass adopted a type-derived override (see the client doc).
+  (bala)
 - 2026-07-28 — Code-review hardening: (1) `getCreateItem` now **refreshes `isFulfillable` on
   existing items** when NetSuite's value differs (not create-only), mirroring the serialized flag;
   diff-only PUT keeps re-syncs no-op. (2) The two other `/items` creation paths
@@ -131,3 +157,5 @@ nearly everything resolves to `fulfillable = 1`.**
 - [Phase 2 — isFulfillable propagation up the SO↔PO chain (2.0)](../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md).
 - [isFulfillable multi-client backfill (worker)](../../worker/workflows/isfulfillable-multi-client-backfill.md)
   — the cross-client catch-up cron and its client-DB / catalog-matching gotchas.
+- [Compass isFulfillable — Data Quality & the Type-Derived Rule](../../../clients/compass-usa/features/isfulfillable-data-quality-and-type-rule.md)
+  — measured prod state, the structural reach limit, and the Compass override + its write-time guard.

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

@@ -7,10 +7,10 @@
 | [Compass Partial In-Transit & Delivered Emails (per package)](features/compass-partial-in-transit-delivered-emails.md) | Compass USA and Compass Canada send a **per-package** in-transit email (and a matching delivered email) instead of one email listing the whole order. | worker/crons/toga2/compass/update_salesorder_status_from_odp.php, worker/crons/toga2/compasscanada/update_salesorder_status_from_odp.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php, worker/crons/toga2/compasscanada/send_delivered_email.php, worker/crons/toga2/compasscanada/workflow/test_partial_in_transit_email.php, worker/crons/toga2/compasscanada/workflow/test_partial_delivered_email.php, library/app/client/compasscanada.php |
 | [Elite TOGA 2.0 → TOGaDeskSupport Standalone Attachment Sync](features/elite-togadesk-attachment-sync.md) | `sync_togadesk_elite_attachments.php` is a standalone cron (every 5 minutes) that syncs file attachments from TOGA 2.0 into TOGaDeskSupport for Elite. | worker/crons/toga2/elite/sync_togadesk_elite_attachments.php, worker/crons/toga2/elite/test_sync_togadesk_elite_attachments.php |
 | [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/checker.php, worker2/Component/Forecast/SaleImport/SaleImport.php, test/@dave/looper.php, test/@dave/reconcile_netsuite_totals.php, test/@dave/fixer.php, test/@dave/analyze_netsuite_forecast_diff.php, test/@dave/trueup_sales.php, test/@dave/reconcile_drift_2023plus.php, test/@dave/probe_invoice_gap_2026.php, test/@dave/probe_creditmemo_gap_detail.php, test/@dave/trueup_open_orders.php, test/@dave/loop_trueup_open_orders.php, test/@dave/trueup_opportunities.php, test/@dave/probe_sales_gap_direct.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_profit_invoices.php, test/@dave/probe_profit_gap.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php, worker/crons/toga2/forecast2/periodic_forecast_discrepancy_fix_open_orders.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/schedules/cron.worker.infrastructure.json |
-| [NetSuite → TOGa Supply Per-Client Sync (thin wrappers)](features/netsuite-togasupply-per-client-sync.md) | Syncs NetSuite transactions (sales orders, purchase orders, invoices, item receipts, item fulfillments, inventory adjustments) into each TOGa Supply (2.0) clien | worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_canon.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql, library/app/api/netsuite/rest.php, library/app/systemmonitor/netsuiteintegration.php |
+| [NetSuite → TOGa Supply Per-Client Sync (thin wrappers)](features/netsuite-togasupply-per-client-sync.md) | Syncs NetSuite transactions (sales orders, purchase orders, invoices, item receipts, item fulfillments, inventory adjustments) into each TOGa Supply (2.0) clien | worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_canon.php, worker/crons/toga2/netsuite/sync_togasupply_elite.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql, library/app/api/toga2.php, library/app/api/netsuite/rest.php, library/app/framework.php, library/app/systemmonitor/netsuiteintegration.php, test/@srija/Elite Testing/Service Requests/test_sync_togasupply_elite_section.php, test/@srija/Elite Testing/Service Requests/test_diagnose_togasupply_elite.php |
 | [OneUptime Server monitor + disk/memory hygiene on the 1.0 worker EB host](features/oneuptime-server-monitor-host-hygiene.md) | The 1.0 `agilant-worker` EB environment runs on the **legacy Amazon Linux 1 PHP 7.2 platform** (Apache httpd/prefork, s3fs mounts, cron) and repeatedly went dow | worker/.ebextensions/040_disk_memory_hygiene.config, worker/.ebextensions/045_oneuptime_agent.config, worker/ebs/cron.worker.php, worker/ebs/mount-s3fs-folders.php, worker/ebs/apache_settings.php, worker/ebs/setup_phpini.php |
 | [OneUptime external uptime monitoring for 1.0 workers](features/oneuptime-worker-uptime-monitoring.md) | Every 1.0 worker box self-reports its liveness to an external OneUptime monitor once per minute by curl-POSTing to a per-worker "Incoming Request" heartbeat URL | library/app/worker.php, worker/crons/worker/worker_heartbeat.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 |
 | [Diagnosing frozen 1.0 worker cron check-ins (Sentry "missed" flood)](workflows/diagnosing-frozen-cron-checkins.md) | When 1.0 worker cron timestamps freeze and Sentry project `worker1` fills with **`missed`** check-ins, the intuitive diagnosis — a wedged `App_Framework::isProc | worker/.ebextensions/cron.config, library/app/worker.php |
 | [isFulfillable Multi-Client Backfill (all togasupply clients)](workflows/isfulfillable-multi-client-backfill.md) | One-time backfill that catches up `Items.isFulfillable` on **existing** items across **all 17 togasupply clients** (AIG, Broward Sheriff, Canon, Endeavor Health | worker/crons/toga2/netsuite/backfill_isfulfillable_all_clients.php, library/app/api/toga2.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 |
+| [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/crons/toga2/netsuite/sync_togasupply_elite.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql, dbchanges2/_modules/netsuite/2026-08-05 - CLEAN NETSUITE CLINET.SQL |

package/knowledge/1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md

@@ -6,20 +6,27 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-11
-owners: ["dfranks", "bala", "jcardinal", "mhammontree"]
+updated: 2026-08-12
+owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
   - worker/crons/toga2/netsuite/sync_togasupply_canon.php
+  - worker/crons/toga2/netsuite/sync_togasupply_elite.php
   - worker/schedules/cron.worker.sync.json
   - dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql
+  - library/app/api/toga2.php
   - library/app/api/netsuite/rest.php
+  - library/app/framework.php
   - library/app/systemmonitor/netsuiteintegration.php
+  - test/@srija/Elite Testing/Service Requests/test_sync_togasupply_elite_section.php
+  - test/@srija/Elite Testing/Service Requests/test_diagnose_togasupply_elite.php
 related:
   - ../architecture.md
   - forecast2-netsuite-reconciliation.md
+  - ../workflows/onboarding-client-to-netsuite-togasupply-sync.md
   - ../../library/features/toga2-api-client-and-bridge.md
   - ../../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
+  - ../../../clients/elite/features/netsuite-togasupply-sync.md
 ---
 
 ## Summary
@@ -54,11 +61,61 @@ through the public TOGa2 API (a 1.0↔2.0 bridge).
 Each section (sales orders, POs, invoices, item receipts, item fulfillments, inventory
 adjustments) uses **adaptive time-windowing** via `startModeIteration()`/`finishModeIteration()`:
 a window stored as `<seconds>-<STATE>` in the client's `Parameters` table shrinks ÷3 when the
-prior run was left `RUNNING` (didn't finish) and grows ×3 (capped at 432000s = 5 days) when it
+prior run was left `RUNNING` (didn't finish) and grows ×3 (capped at
+`MAX_TIME_WINDOW_TO_FETCH_FROM_NETSUITE_SECONDS`, default 432000s = 5 days) when it
 finished `IDLE`. The window state is written `RUNNING` at the **start** of each section, so a
 crash leaves it visibly RUNNING and the next run backs off. `LAST_SYNC_DATETIME_*` advances to
 the window's upper bound after each successful section.
 
+### The window cap is per-client overridable (2026-08-12)
+
+`common_sync_togasupply.php:3` is
+`defined('MAX_TIME_WINDOW_TO_FETCH_FROM_NETSUITE_SECONDS') || define(…, 432000)` — **not** a
+`const` — so a wrapper may `const MAX_TIME_WINDOW_TO_FETCH_FROM_NETSUITE_SECONDS = …;`
+*before* its `require_once` to widen its own catch-up window. Only Elite does (2592000 = 30 days,
+while backfilling from 2024); the other 17 wrappers inherit the 5-day default. Use this only for a
+deep backfill and put the reason in a comment next to it — at 5-day windows on a 5-minute cron,
+~858 days of history takes days of wall-clock to catch up; at 30 days it took ~90 minutes.
+
+### ⚠ A shrinking window is a BUG SIGNAL, not a load signal
+
+The single most expensive misreading of this engine. `startModeIteration()` writes
+`<seconds>-RUNNING` at the **start** of every section and `finishModeIteration()` writes `-IDLE` at
+the end; the ÷3 `REDUCE_INTERVAL_FACTOR` shrink fires only because the *previous* run never reached
+its IDLE write. **There is no timeout, memory cap, or resource limit anywhere in the script** — so
+"didn't finish" can only mean **it threw**. A collapsing window therefore means *go read Sentry*,
+never *tune the window size down*. (Corollary: a window that has grown back to the cap is positive
+evidence the section is completing.)
+
+### ⚠ A per-record API failure does NOT stop the cursor — the record is skipped forever
+
+The cursor write (`LAST_SYNC_DATETIME_*`) and `finishModeIteration()` both run **unconditionally
+after** the record loop. A record that throws mid-loop is captured to Sentry and **stepped over**,
+while the section still reports success and advances the cursor past its window. So
+**"section IDLE + cursor advancing" is not proof of a complete import** — it only proves the run
+didn't die.
+
+Proven concretely on Elite: sales order **169441** (NetSuite internal id 4624062, trandate
+2024-04-15, customer PO `BEGGS/04152024/…`) was simply absent from `Client_Elite.SalesOrders`
+because its window ran ~15 minutes before the missing-vendor fix (below) landed.
+
+**Recovery: rewind the section's cursor.** Set `NETSUITE_LAST_SYNC_DATETIME_<SECTION>` in the
+client's `Parameters` table back before the lost window. Re-import is **idempotent** — records match
+on `c_netsuiteInternal*Id` and `SalesOrders.c_netsuiteInternalSalesOrderId` carries a unique index —
+so a rewind re-PUTs what is already there and POSTs only what is missing.
+
+### Sections are NOT order-dependent — one cursor can be rewound alone
+
+Each section's `startModeIteration()` reads only **its own** `Parameters` key, and the PO section
+resolves its own sales order: `syncPurchaseOrderFromNetsuite()` calls
+`syncSalesOrderFromNetsuite()` itself (`library/app/api/toga2.php:1813`) when a PO has an
+originating order, and the link is conditional (`if ($salesOrder)` at :2221) so a PO whose order
+cannot be resolved still imports. Consequences worth knowing before you "fix" a skew:
+
+- A purchase-orders cursor running 50 days **ahead** of sales-orders is safe, not a defect.
+- Rewinding one section without touching the others is safe.
+- Which is also why the per-section operator script below is a legitimate tool rather than a hack.
+
 ### Adding a new client (the full recipe)
 
 A wrapper + schedule alone is **not enough** — the client must also be provisioned in three
@@ -127,6 +184,30 @@ them provisioned: `/customers`→`c_netsuiteInternalCustomerId`; `/countries`→
 `/shipping-methods`→`c_netsuiteInternalShipMethodId`. The names are a **convention**, not
 discovered per-client.
 
+### Manual operator scripts (built for Elite, reusable pattern)
+
+Two CLI scripts written for the Elite backfill live under
+`test/@srija/Elite Testing/Service Requests/` (they are operator tools, **not** scheduled crons —
+do not add them to `cron.worker.sync.json`):
+
+- **`test_sync_togasupply_elite_section.php`** — runs **one** section by enabling only its
+  `IS_ENABLED_INTEGRATION_*` flag with `define()` instead of `const`, so a slow section can be
+  backfilled without the earlier sections eating the run. **It is NOT a dry run — it writes the real
+  cursors.**
+- **`test_diagnose_togasupply_elite.php`** — **read-only** per-record IMPORT/SKIP match reporter for
+  a given section and date range. It deliberately does **not** call
+  `App_Framework::cronInitialization()` (that takes the process lock and exits silently, and writes a
+  `CronJobExecutions` row) and it drains/disables output buffering so `echo` actually reaches the
+  terminal.
+
+**⚠ A manual script does not mutually exclude with the scheduled cron.**
+`App_Framework::isProcessRunning()` (`library/app/framework.php:833-842`) defaults to
+`$_SERVER['SCRIPT_FILENAME']` and greps `ps -ef` for **its own filename** — so a per-section script
+with a different filename runs happily *alongside* `sync_togasupply_<client>.php`. Both then race the
+same `Parameters` cursors: whoever writes last wins and the other's window is silently skipped
+(and windows shrink). Any manual backfill must either pass the cron's filename to
+`isProcessRunning()` explicitly or be run with the cron's schedule entry disabled.
+
 ## Data model
 
 Per-client `Parameters` table (2.0 client DB, e.g. `Client_Canon.Parameters`; columns
@@ -149,6 +230,44 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
 
 ## Gotchas / known issues
 
+- **A client with NEITHER a manufacturer NOR a catalog on its items used to crash the whole run
+  (fixed 2026-08-12).** `$lookupItemByClientUuidAndPartNumberUpper[$uuidClient]` and
+  `$lookupAllCatalogItemsByClientUuidAndPartNumberUpper[$uuidClient]` were only keyed **inside** the
+  items loop, so a sparse client never got the key created at all. Every `sync*FromNetsuite()` takes
+  them as `array &`, so the unset key passed as **null** →
+  `TypeError: Argument 8 passed to App_Api_Toga2::syncSalesOrderFromNetsuite() must be of the type
+  array, null given`. Both are now initialised to `[]` at `common_sync_togasupply.php:74-75`, before
+  the loop. This was **shared** code — the latent bug was reachable by any sparse client and Elite's
+  three initial items (both fields null) merely exposed it. Lesson for this engine: any per-client
+  lookup passed by reference must be initialised **outside** the loop that fills it.
+- **Countries are auto-created from the NetSuite shipping address, with a malformed code and name.**
+  `library/app/api/toga2.php:696-730` (and a duplicate at :1868-1905): when
+  `$nsShippingAddress->country` is not in `$lookupCountryByNetsuiteCountry`, the sync **POSTs
+  `/countries`**, deriving the name by splitting on non-lowercase characters and the code as
+  `substr(word1,0,1) . substr(word2,1,1)`. NetSuite's **leading underscore is never stripped**, so
+  `_unitedKingdom` → name `_united Kingdom` / code `_i`; `_canada` → `_canada` / `_C`;
+  `_australia` → `_australia` / `_A`. **Codes can collide.** An address with an *empty* country sets
+  `$isInvalidAddress = true` instead. The rows then surface in any UI that shows a country.
+  **Remedy: pre-seed `Countries`** with the correct `code`/`name` **and** the exact
+  `c_netsuiteCountry` string before the first import — see the onboarding workflow.
+  Note the direction: **NetSuite → TOGa only.** Nothing in this cron ever writes to NetSuite (every
+  NetSuite call is a `list*`/`fetch*`), and NetSuite's country list is a fixed system list that
+  cannot be extended, so there is nothing to fix on the NetSuite side.
+- **Item receipts are matched by the originating PO's customer, NOT by warehouse location.**
+  `common_sync_togasupply.php:844-905` uses the warehouse location ids only to **narrow** the SuiteQL
+  query; interest is decided from the receipt's `createdFrom` purchase order — its shipTo customer,
+  falling back to the custom field `NETSUITE_CUSTOM_FIELD_ID__END_USER_CUSTOMER`. So: a receipt from
+  a **stock PO** with no shipTo and no end-customer cannot be attributed to any client and is
+  skipped; and because the location filter is shared, receipts belonging to **other** clients at a
+  shared warehouse are returned and correctly skipped. Modelling receipts as "location-matched"
+  produces wrong diagnostics.
+- **`Units.locationId` is never populated by this sync — transaction location lives on the item
+  rows.** All 229 `Client_Elite.Units` have `locationId` NULL. `locationId` exists only on `Units`
+  and `InventoryAdjustmentItems` (not on the `*ItemUnits` bridge tables), and
+  `InventoryAdjustmentItems.locationId` **is** correctly populated (Elite: 6 rows at NetSuite
+  location 196 "Elite"/Chicago, 1 at 5 "New York"). Aggregate `_qtyOnHand` derives from
+  `ItemReceiptItems` joined through `PurchaseOrderItems` → `VendorItems`, not from
+  `Units.locationId`. When building an inventory view, read location from the **transaction items**.
 - **⚠ OPEN, UNTRACKED (found 2026-08-11): the GroWrk item-receipt sync has been failing every 5
   minutes since 2026-08-06.** `Logs.Issue` **124** for `clientId` **33**, *"Invalid API Response"* from
   `App_Api_Toga2::send()` (`library/app/api/toga2.php:3245`) via
@@ -245,6 +364,24 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
 
 ## Change history
 
+- 2026-08-12 — TRUE-80499 (Elite onboarding, shared-engine work). **Fixed** the sparse-client
+  `TypeError`: the two per-client item lookups are now initialised at
+  `common_sync_togasupply.php:74-75` instead of only inside the items loop, so a client whose items
+  have neither a manufacturer nor a catalog no longer passes `null` into an `array &` parameter.
+  **Built** the per-client window override (`MAX_TIME_WINDOW_TO_FETCH_FROM_NETSUITE_SECONDS` is now
+  `defined()||define()`, so a wrapper can widen its catch-up window; Elite uses 30 days, the other 17
+  stay at 5). Recorded four corrections that cost real diagnostic time: a **shrinking window is a bug
+  signal, not a load signal** (nothing in the script has a timeout — "didn't finish" means "threw");
+  a **per-record failure does not stop the cursor**, so the record is skipped permanently while the
+  section still reports IDLE and advances (recovery = rewind `NETSUITE_LAST_SYNC_DATETIME_<SECTION>`;
+  re-import is idempotent); **sections are independent** so one cursor can be rewound alone and a
+  skewed PO cursor is not a defect; and **item receipts are attributed via the `createdFrom` PO's
+  customer**, not by warehouse location. Also recorded the **malformed auto-created countries**
+  (`_unitedKingdom` → code `_i`), that `Units.locationId` is never populated by this sync, and the two
+  Elite operator scripts plus the `isProcessRunning()` own-filename trap that lets a manual script
+  race the scheduled cron. Client-specific results in
+  [Elite NetSuite → TOGa Supply sync](../../../clients/elite/features/netsuite-togasupply-sync.md).
+  (snaredla)
 - 2026-08-11 — TRUE-80824 (side finding, no code change): recorded an **open, untracked** failure —
   GroWrk (`clientId` 33) `syncItemReceiptFromNetsuite` has raised "Invalid API Response" from
   `App_Api_Toga2::send()` every 5 minutes since 2026-08-06 (`Logs.Issue` 124, ~288 events/day).

package/knowledge/1.0/apps/worker/workflows/isfulfillable-multi-client-backfill.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: workflow
 status: active
-updated: 2026-07-28
+updated: 2026-08-12
 owners: [bala]
 files:
   - worker/crons/toga2/netsuite/backfill_isfulfillable_all_clients.php
@@ -16,6 +16,7 @@ related:
   - ../../library/features/netsuite-item-isfulfillable-sync.md
   - ../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md
   - ../../../clients/compass-usa/profile.md
+  - ../../../clients/compass-usa/features/isfulfillable-data-quality-and-type-rule.md
 ---
 
 ## Summary
@@ -46,6 +47,20 @@ recursive up-chain propagation** — it never writes the DB directly and never w
    beta/sandbox endpoint.
 
 ## Gotchas / known issues
+- **⚠⚠ Re-running this backfill CANNOT close the remaining NULLs — they are structurally
+  unreachable (verified prod, 2026-08-12).** The cron only re-PUTs **Agilant source** items and
+  relies on the api2 interceptor to walk up the chain, which requires the client PO to have an
+  Agilant-tier SO behind it (a `PurchaseOrderItems_SalesOrderItems` row). **Vendor-direct POs have
+  none.** In prod `Client_Compass`, **zero** items with `isFulfillable IS NULL` reach the Agilant
+  tier (vs **52,990** line-level reaches for `isFulfillable = 1` items). Per vendor — items ordered /
+  reaching the Agilant tier: OFFICE DEPOT **497/124**; STRATEGIC SYSTEMS **66/0**; FREEDOM GROUPS LLC
+  **61/0**; PRESIDIO **45/0**; COMPASS GROUP **35/0**; ENCOMPASS SUPPLY CHAIN **2/0**. Only ODP
+  partially routes through Agilant NetSuite. **Do not schedule another run expecting these to fill
+  in** — closing the gap needs a different data source (see the
+  [Compass data-quality doc](../../../clients/compass-usa/features/isfulfillable-data-quality-and-type-rule.md)).
+- **⚠ Compass Canada was never covered by this run.** `Client_CompassCanada` is **220 items, 100%
+  NULL** as of 2026-08-12 — the storefront Qty Fulfilled cell is dead across the entire Canada
+  tenant. Canada is not in the 17-client list above and has never been stamped at all.
 - **Agilant catalog is matched by NAME, not id.** `Catalogs.name = 'Agilant'` is stable across every
   client, but the `catalogId` **differs per client** — **Quad = 2, all other clients = 1** (verified
   across all 17 client DBs). Hardcoding `catalogId = 2` would silently hit only Quad and miss the
@@ -73,6 +88,11 @@ recursive up-chain propagation** — it never writes the DB directly and never w
   client backfilled from all its Agilant items.
 
 ## Change history
+- 2026-08-12 — Prod audit of the post-run state: recorded that the remaining NULLs are
+  **structurally unreachable by this cron** (vendor-direct POs have no Agilant-tier SO for the
+  interceptor to walk; 0 NULL Compass items reach the Agilant tier, with per-vendor reach counts),
+  and that **Compass Canada was never covered** (220 items, 100% NULL). Post-run Compass state:
+  770 NULL / 25 zero / 697 one, with 12,318 order lines fulfilled but flagged NULL. (bala)
 - 2026-07-28 — Built and ran the multi-client `backfill_isfulfillable_all_clients.php`: direct
   client-DB scoping of Agilant-catalog items (matched by `Catalogs.name`, not id) keyed by
   `c_netsuiteInternalItemId`, NetSuite reads by internal id (cached across clients), re-PUT to api2 so

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

@@ -6,14 +6,19 @@ project: Worker
 client: shared
 type: workflow
 status: active
-updated: 2026-06-16
-owners: ["dfranks"]
+updated: 2026-08-12
+owners: ["dfranks", "snaredla"]
 files:
   - worker/crons/toga2/netsuite/sync_togasupply.php
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
+  - worker/crons/toga2/netsuite/sync_togasupply_elite.php
   - worker/schedules/cron.worker.sync.json
   - dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql
-related: []
+  - dbchanges2/_modules/netsuite/2026-08-05 - CLEAN NETSUITE CLINET.SQL
+related:
+  - ../features/netsuite-togasupply-per-client-sync.md
+  - ../../../clients/elite/features/netsuite-togasupply-sync.md
+  - ../../../2.0/apps/dbchanges2/workflows/client-schema-drift-audit.md
 ---
 
 ## Summary
@@ -49,6 +54,71 @@ API (`App_Api_Toga2::send`), which lands in that client's `Client_<Name>` databa
 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.
+6. **Seed the shared synthetic "Agilant" vendor row** — see the dedicated section below. The
+   `netsuite` dbchanges2 module does **not** do it, and without it every order carrying a customer PO
+   number fails.
+7. **Grant `AclCustomFieldPermissions` for the module's custom fields** — also below. The `netsuite`
+   module registers `CustomRecordFields` rows and adds the `c_` columns but grants **no field-level
+   ACL**, so api2 answers `403 EV-2`.
+8. **Pre-seed `Countries`** for every country the client ships to, with the correct `code`/`name`
+   **and** the exact NetSuite `c_netsuiteCountry` string (`_unitedKingdom`, `_canada`, …). If you
+   skip this, the sync auto-creates the row from the NetSuite string and derives a **malformed**
+   name and a collision-prone 2-char code — mechanics and examples in the
+   [engine doc](../features/netsuite-togasupply-per-client-sync.md).
+9. **Widen the window only if you are backfilling deep history.** A wrapper may
+   `const MAX_TIME_WINDOW_TO_FETCH_FROM_NETSUITE_SECONDS = …;` before the `require_once` (Elite: 30
+   days while backfilling from 2024). At the 5-day default on a 5-minute cron, ~2.4 years of history
+   takes days to catch up.
+
+## The synthetic "Agilant" vendor must exist in the client's own DB (found 2026-08-06)
+
+13 of the 18 wrappers pass the **same** vendor uuid
+`10ed18ec-0999-53d9-f9db-5892d90f09d4` ("Agilant") as
+`CLIENT_CONFIGURATION['importCustomerPurchaseOrdersOnVendor']` — but `Vendors` is a **per-client
+table**, so that uuid has to exist as a row in **every** `Client_<Name>.Vendors`. **Nothing in
+`dbchanges2/_modules/netsuite/` seeds it** (verified: the uuid appears in no file in the repo).
+
+Symptom when it is missing: **every** sales order that carries a customer PO number (NetSuite
+`otherRefNum`) fails `POST /purchase-orders` with **400 `EV-12` "unable to find a unique match"** on
+the nested vendor. Orders without a customer PO import fine, so the failure looks partial and
+data-dependent rather than structural. On Elite this produced **191 Sentry events in one day**
+(`WORKER1-420`) and `PurchaseOrders` stuck at **0**; after seeding the row it went to **234**.
+
+Seed it with a `dbchanges2/Client_<Name>/<YYYY-MM-DD><letter> - <Name>AgilantVendor.sql` inserting
+the vendor with that **exact** uuid (reuse it — a fresh UUID defeats the whole shared-uuid pattern).
+
+> **The undocumented pattern to internalise: a uuid shared across clients still needs a row per
+> client database.** It reads like a global id and behaves like a per-tenant one.
+
+## The `netsuite` module grants no field-level ACL (found 2026-08-06)
+
+`dbchanges2/_modules/netsuite/2026-08-05 - CLEAN NETSUITE CLINET.SQL` inserts the
+`CustomRecordFields` rows and adds the `c_` columns but contains **zero**
+`AclCustomFieldPermissions` statements (`grep -c` = 0; the smaller
+`2026-07-10a - UnitInventoryFields.sql` *does* grant, which is why the gap is easy to miss).
+
+Symptom: api2 returns **403 `EV-2` "do not have the necessary permissions to read the specified
+fields"** — a whole-request failure, not a silently dropped field.
+
+Measured on Elite vs. a healthy client: **Elite 27 fields / 0 grants; Quad 26 / 25** grants to
+**role 1 (Base), `isWritable = 1`**. Fixed with
+`dbchanges2/Client_Elite/2026-08-06a - EliteNetsuiteCustomFieldAcl.sql`. Same failure class as the
+GroWrk incidents — the general audit playbook is
+[client schema-drift audit](../../../2.0/apps/dbchanges2/workflows/client-schema-drift-audit.md).
+
+**Post-onboarding check, per client:** every `CustomRecordFields` row added by the module should have
+exactly one grant. Count fields vs. grants and diff against a known-good client before declaring the
+onboarding done.
+
+## Recovering records the first run skipped
+
+A record that throws mid-loop is logged to Sentry and **stepped over while the cursor still
+advances** — so a clean-looking IDLE section can be missing records (see the engine doc). Recovery is
+to rewind `NETSUITE_LAST_SYNC_DATETIME_<SECTION>` in the client's `Parameters` table to before the
+bad window. Re-import is **idempotent** (matched on `c_netsuiteInternal*Id`;
+`SalesOrders.c_netsuiteInternalSalesOrderId` has a unique index) and sections are independent, so one
+cursor can be rewound alone. Expect to do this at least once on any onboarding where a provisioning
+gap was found *after* the cron started running.
 
 ## Parameters seed (the required, easily-missed step)
 The sync reads/writes per-client sync state via the TOGa2 API `/parameters` endpoint, which
@@ -103,11 +173,30 @@ the directory; no `USE`).
   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.
+- **⚠ CORRECTED 2026-08-12 — a failing record does NOT self-heal.** This section previously said
+  "the checkpoint does not advance past a throwing window, so it self-heals once the dependency
+  exists." **That is wrong for a per-record failure.** The cursor write and `finishModeIteration()`
+  run unconditionally *after* the record loop, so a record that throws is Sentry-logged, stepped
+  over, and **permanently skipped** while the section reports success. Only a throw that escapes the
+  loop (setup/lookup phase, transport) leaves the checkpoint behind. Fix a provisioning gap and you
+  must **rewind the cursor** — see *Recovering records the first run skipped* above.
+- **⚠ OPEN: `dbchanges2/_modules/netsuite/2026-08-05 - CLEAN NETSUITE CLINET.SQL` sits in the
+  SHARED module folder** and will run against **all 18 opted-in clients** on the next unscoped run.
+  It also carries a `CLINET` typo and **no letter suffix**, which the dbchanges2
+  `YYYY-MM-DD<letter>` contract requires. Know it is there before you trigger a module run.
 
 ## Change history
+- 2026-08-12 — TRUE-80499 (Elite): added the **three provisioning steps this workflow was missing**,
+  each found by a production failure rather than by reading the module. (1) The shared synthetic
+  **"Agilant" vendor** uuid `10ed18ec-…f09d4` must be seeded as a **row in every**
+  `Client_<Name>.Vendors` — nothing in the `netsuite` module does it, and without it every order with
+  a customer PO number 400s `EV-12` on the nested vendor (Elite: 191 Sentry events/day, PurchaseOrders
+  0 → 234 after seeding). (2) The module registers `CustomRecordFields` and the `c_` columns but grants
+  **no `AclCustomFieldPermissions`** → 403 `EV-2` (Elite 27 fields / 0 grants vs. Quad 26 / 25 to role
+  1). (3) **Pre-seed `Countries`** or the sync auto-creates malformed rows from the NetSuite string.
+  Also added the per-client backfill-window override, a **cursor-rewind recovery** procedure, and
+  **corrected** this doc's claim that a throwing record self-heals — it does not, the cursor advances
+  past it. Flagged the unsuffixed shared `CLEAN NETSUITE CLINET.SQL` as an open hazard. (snaredla)
 - 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)

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

@@ -23,7 +23,7 @@
 | [Record-Changed Event Publishing (_Event::publish to SQS)](features/event-publish-sqs.md) | `_Event::publish()` (in `_underscore/Event.php`) is the PHP side of the real-time event pipeline. | _underscore/Event.php |
 | [FIELD_STORAGE fields — per-row lazy hydration and the platform-wide missing-column 500](features/field-storage-row-hydration.md) | `FIELD_STORAGE` is the 2.0 field type for blob-backed columns (S3 or local folder). | _underscore/Model.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/Invoice.php, dbchanges2/Core/HISTORIC/2024/2024-11b - item-fulfillments.sql |
 | [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). | worker2/Component/Forecast/SaleImport/SaleImport.php, worker2/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/probe_je_shape.php, test/@dave/fixer.php, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/Junk Drawer/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
-| [isFulfillable Propagation Up the SO↔PO Chain](features/fulfillable-item-propagation.md) | `Items.isFulfillable` is a boolean that gates whether a storefront line's **Qty Fulfilled** cell is actionable. | _underscore/Model/Client/Item.php, _underscore/Model/Compass/Item.php, dbchanges2/Core/2026-07-17 - Items isFulfillable RecordField.sql, dbchanges2/Core/2026-07-17 - RegisterItemIsFulfillableInterceptors.sql, dbchanges2/Client/2026-07-17 - ItemsisFulfillable.sql |
+| [isFulfillable Propagation Up the SO↔PO Chain](features/fulfillable-item-propagation.md) | `Items.isFulfillable` is a boolean that gates whether a storefront line's **Qty Fulfilled** cell is actionable. | _underscore/Model/Client/Item.php, _underscore/Model/Compass/Item.php, toga2-supply/src/pages/Orders/view/OrderView/components/sections/OrderItemsTableSection.tsx, dbchanges2/Core/2026-07-17 - Items isFulfillable RecordField.sql, dbchanges2/Core/2026-07-17 - RegisterItemIsFulfillableInterceptors.sql, dbchanges2/Client/2026-07-17 - ItemsisFulfillable.sql |
 | [Item-Fulfillment Stage Lifecycle (picked/packed/shipped) & Order Status](features/item-fulfillment-stage-lifecycle-and-order-status.md) | Every ItemFulfillment (IF) now carries an explicit **stage** — picked → packed → shipped — resolved through `ItemFulfillmentStages → ItemFulfillmentStatuses` (m | _underscore/Model/Client/SalesOrder.php, _underscore/Model/Quad/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/SalesOrderStatus.php, _underscore/Model/Client/SalesOrderItem.php, _underscore/Model/Client/Item.php, _underscore/Model/Client/PurchaseOrderItem.php, library/app/api/toga2.php, dbchanges2/Client/2026-06-30a - BackfillNullStageItemFulfillmentsToShipped.sql, dbchanges2/Client/2026-06-30b - SalesOrderStatusesPickedPacked.sql, dbchanges2/Client/2026-06-30c - ItemFulfillmentStageIdNotNull.sql, dbchanges2/Client_CompassCanada/2026-06-30a - ItemFulfillmentLifecycleAndShippedBackfill.sql |
 | [DB-free unit testing for _underscore model interceptors](features/model-interceptor-unit-testing.md) | `_underscore` shipped with **no** PHPUnit setup (no `composer.json`/`phpunit`; only vendored PhpOffice tests existed). | _underscore/Test/bootstrap.php, _underscore/Test/Prudential/ServiceRequestTest.php, test/@Bala/tests/netsuite_salesorder_payload_tests.php |
 | [_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, _underscore/Model.php, _underscore/Model/Rate/Subscription.php |

package/knowledge/2.0/apps/_underscore/features/fulfillable-item-propagation.md

@@ -6,11 +6,12 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-28
+updated: 2026-08-12
 owners: [bala]
 files:
   - _underscore/Model/Client/Item.php
   - _underscore/Model/Compass/Item.php
+  - toga2-supply/src/pages/Orders/view/OrderView/components/sections/OrderItemsTableSection.tsx
   - dbchanges2/Core/2026-07-17 - Items isFulfillable RecordField.sql
   - dbchanges2/Core/2026-07-17 - RegisterItemIsFulfillableInterceptors.sql
   - dbchanges2/Client/2026-07-17 - ItemsisFulfillable.sql
@@ -18,6 +19,7 @@ related:
   - recursive-item-fulfillments.md
   - ../../../1.0/apps/library/features/netsuite-item-isfulfillable-sync.md
   - ../../../clients/compass-usa/profile.md
+  - ../../../clients/compass-usa/features/isfulfillable-data-quality-and-type-rule.md
 ---
 
 ## Summary
@@ -78,6 +80,35 @@ same bridge topology, walked for a different payload (a scalar flag rather than
   too** — the same integrity class as the Compass off-by-one bridge bugs (see
   [MITS PO → SO Item Linking](../../../clients/compass-usa/features/mits-po-to-so-item-linking.md)).
 
+## Reach limit — vendor-fulfilled items can NEVER be reached (structural, verified 2026-08-12)
+The walk only reaches a client item whose PO has an **Agilant-tier SO behind it** (a
+`PurchaseOrderItems_SalesOrderItems` row). **Vendor-direct POs have none**, so an item that is only
+ever fulfilled by an outside vendor **can never receive `isFulfillable` from this pipeline** — no
+amount of re-running the backfill changes that. It is a **structural gap, not a catch-up gap.**
+
+Prod `Client_Compass` (2026-08-12): **zero** items with `isFulfillable IS NULL` reach the Agilant
+tier, versus **52,990** line-level reaches for `isFulfillable = 1` items. Per vendor (Compass items
+ordered / reaching the Agilant tier): OFFICE DEPOT **497/124**; STRATEGIC SYSTEMS **66/0**; FREEDOM
+GROUPS LLC **61/0**; PRESIDIO **45/0**; COMPASS GROUP **35/0**; ENCOMPASS SUPPLY CHAIN **2/0**. Only
+ODP partially routes through Agilant NetSuite. Full analysis + the remediation options:
+[Compass isFulfillable data quality & type rule](../../../clients/compass-usa/features/isfulfillable-data-quality-and-type-rule.md).
+
+## Where the flag is consumed (frontend gate)
+`toga2-supply/src/pages/Orders/view/OrderView/components/sections/OrderItemsTableSection.tsx` —
+`isQtyFulfilledClickable` (~lines 21–30) gates the **Qty Fulfilled** cell on:
+
+```
+String(item?.Items?.isFulfillable) === "1" && Number(item?._qtyFulfilled) !== 0
+```
+
+- **`NULL` and `0` behave identically here** — both make the cell dead.
+- The gate also carries a **hardcoded Compass exception**
+  (`hostName === COMPASS && AssetTypes.name === 'FEE' → false`) that duplicates the proposed
+  type-derived data rule; it should be **deleted once that rule lands in the DB** so the logic lives
+  in one place.
+- Because the gate *also* requires `_qtyFulfilled !== 0`, an item that has never been fulfilled is
+  unclickable regardless of the flag's value.
+
 ## Data model / schema (deploy)
 Three `dbchanges2` migrations register the field + hooks; **all must be present in the target
 env or the flag write is rejected:**
@@ -90,9 +121,16 @@ env or the flag write is rejected:**
 
 ## Conflict rule
 Multi-source kits (an item reachable from more than one source) use **LAST-WRITER-WINS**. A
-deterministic `MIN`/`MAX` aggregate was **deliberately deferred** — harmless while values are
+deterministic `MIN`/`MAX` aggregate was **deliberately deferred** on the assumption that values are
 uniformly `1` (see the Phase-1 gotcha: NetSuite flags nearly everything fulfillable).
 
+**⚠ That assumption is no longer safe (2026-08-12).** Prod `Client_Compass` holds **25 items with
+`isFulfillable = 0`** — all bundle headers, **14 with real fulfillments** (worst case `B4NY9UC`:
+11,062 order lines / 2,864 fulfillment rows, its Qty Fulfilled cell disabled). NetSuite marks
+group/kit **headers** `F`, but in TOGa **the header is the line that ships**. Mixed 0/1 values are
+therefore real, and last-writer-wins can land on the wrong one. See the
+[Compass data-quality doc](../../../clients/compass-usa/features/isfulfillable-data-quality-and-type-rule.md).
+
 ## Client variations
 - **Compass** (USA/Canada, DB `Client_Compass`) is the built/verified client. Its `_Model_Compass_Item`
   overrides `postPost`/`postPut` for a price override, so it **must** `parent::` up to the base or
@@ -123,12 +161,35 @@ uniformly `1` (see the Phase-1 gotcha: NetSuite flags nearly everything fulfilla
   **resolved/substituted at deploy** — it cannot join across clusters at runtime.
 - **⚠ Compass subclass shadowing.** If a future client subclass overrides Items `postPost`/`postPut`
   without calling `parent::`, propagation silently stops for that client.
-- **Product decision unresolved (caveat, not a bug).** Because NetSuite's `isfulfillable` is `T`
-  for services as well as physical goods (see Phase-1 doc), propagation makes **everything**
-  clickable on the storefront. Whether "reflect NetSuite's flag as-is" is the intended behavior —
-  vs. using `itemtype` to hide services — is **pending product confirmation**.
+- **⚠ Chain-propagation writes are INVISIBLE to the audit log (debugging gotcha).**
+  `propagateFulfillableAcrossChain` issues a **raw `UPDATE Items … WHERE id IN (…)` through `_Query`**
+  (`Item.php` ~lines 562–571), bypassing the model layer and therefore the `Logs_<client>` audit
+  trail. A **sync PUT is logged; a chain propagation is silent** — so "no log row" does **not** mean
+  "never written". Use that as the discriminator between the two write paths: Compass item **2383**
+  (Agilant source 2720, NetSuite id 1536664) has **no** log row while 2382/2384/2385 do, which alone
+  identifies which path set each value.
+  **Query anchor:** prod `Core.RecordFields` **id 2434 = `Items.isFulfillable`** (`recordId 21`); join
+  `Logs_<client>.Record` (`recordId = 21`, `primaryKeyId = <itemId>`) to `Logs_<client>.RecordField`
+  `ON logRecordId` with `recordFieldId = 2434`. Same technique applies to any
+  interceptor-vs-propagation debugging.
+- **Product decision — analyzed 2026-08-12, decision taken for Compass (was "unresolved").** Because
+  NetSuite's `isfulfillable` is `T` for services as well as physical goods (see Phase-1 doc),
+  propagation makes **everything** clickable. A prod evidence review showed item **type cannot
+  confirm** fulfillability (0%-tracked types like DESKTOPS are physical) but the **tracking
+  ride-along test can disqualify** fee/software/miscellaneous lines. Compass has since adopted a
+  **type-derived override** of NetSuite's flag, which **must be enforced at write time** because the
+  Phase-1 daily refresh reverts it. Rule, projected impact, caveats:
+  [Compass isFulfillable data quality & type rule](../../../clients/compass-usa/features/isfulfillable-data-quality-and-type-rule.md).
 
 ## Change history
+- 2026-08-12 — Prod investigation (read-only, no code change): recorded the engine's **structural
+  reach limit** (vendor-direct POs have no Agilant-tier SO, so those items can never receive the
+  flag — 0 of the NULL Compass items reach the Agilant tier vs 52,990 reaches for `=1` items),
+  documented the **toga2-supply frontend gate** that consumes the flag (plus its hardcoded Compass
+  `FEE` exception to retire), added the **chain-propagation writes are invisible to the audit log**
+  gotcha with the `Core.RecordFields 2434` / `Logs_<client>` query anchor, and retired the
+  "values are uniformly 1" assumption behind the deferred conflict rule (25 Compass zeros, 14 with
+  real fulfillments). (bala)
 - 2026-07-28 — Fixed a **read-replica routing** bug: `propagateFulfillableAcrossChain`'s source-item
   read and the recursive chain-walk CTE now `setisReadHostEnabled(false)` so they run on the writer
   and see the request's own open write transaction (read-your-writes) — a replica read could return
@@ -151,3 +212,5 @@ uniformly `1` (see the Phase-1 gotcha: NetSuite flags nearly everything fulfilla
   bridge topology.
 - [Compass MITS PO → SO Item Linking](../../../clients/compass-usa/features/mits-po-to-so-item-linking.md)
   — how the SOI↔POI bridges get built (and the integrity bugs that break this walk).
+- [Compass isFulfillable — Data Quality & the Type-Derived Rule](../../../clients/compass-usa/features/isfulfillable-data-quality-and-type-rule.md)
+  — measured prod state, why the NULLs are unreachable, and the Compass override.

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)_ — 17 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 21 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 22 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
 - **togadesk** (TOGa Desk) — 12 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
@@ -18,7 +18,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 54 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 55 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 48 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 22 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 8 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/knowledge/clients/compass-canada/profile.md

@@ -15,12 +15,13 @@ project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-08-06
+updated: 2026-08-12
 owners: [jcardinal, bala, tcox, apeterson]
 files: []
 related:
   - ../compass-usa/profile.md
   - ../compass-usa/features/approval-decision-flow.md
+  - ../compass-usa/features/isfulfillable-data-quality-and-type-rule.md
   - features/french-order-email-localization.md
   - ../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
   - ../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
@@ -104,6 +105,17 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   impact: 34 personas, 7,017 users with personas, 1,461 with more than one. Fix `5313a9b1` exists on
   `TRUE-80672`/`_beta` but is **not in `_production`**. See
   [Client Fields → Login-settings branches](../../2.0/apps/toga2-commerce/features/client-fields.md).
+- **⚠ `Items.isFulfillable` is 100% NULL in Canada — the Qty Fulfilled cell is dead storefront-wide.**
+  All **220** `Client_CompassCanada` items are NULL (prod, 2026-08-12): Canada was **never** included
+  in the multi-client backfill and has never been stamped at all. Note also that Canada uses a
+  **different type vocabulary** than Compass USA — title-case `assetTypes` (`Equipment`, `Hardware`,
+  `Services`, `Fee`, `Consulting`) and its own `itemTypes` (`LAPTOP`, `MACBOOK`, `MONITORS`,
+  `CABLES`, `SERVICE`, `Services`, `CONSULTING`, `SOFTWARE LICENSING`), with **no `FEE` or
+  `SERVICEFEES` itemType at all**. The US-derived rule list still matches, because the columns are
+  `utf8mb4_0900_ai_ci` (case-insensitive) — **do not split it into two hand-maintained lists**, but
+  do re-confirm the Canada vocabulary separately. Projected impact of the proposed rule here: 13 → 0,
+  207 → 1. See
+  [isFulfillable — Data Quality & the Type-Derived Rule](../compass-usa/features/isfulfillable-data-quality-and-type-rule.md).
 - The 2026-06-08 ASN → ItemFulfillment work was for **Compass USA**, not Compass Canada.
 - **Order status is shipped-only**, same as Compass USA (shared `_Model_Compass_SalesOrder`).
   Compass Canada's own IF lifecycle stages (picked/packed/shipped) + shipped backfill are seeded by

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

@@ -5,6 +5,7 @@
 | [Compass Approval-Decision Flow (Notifications & Manager Reassignment)](features/approval-decision-flow.md) | 2.0 | Compass's sales-order approval flow — approval/notification email lists, **manager reassignment**, VIP auto-approve, and EN/FR localization — lives **entirely i | _underscore/Model/Compass/ApprovalDecision.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/Usa/ApprovalDecision.php, _underscore/Model/Compass/Canada/ApprovalDecision.php |
 | [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, dbchanges2/Client_Compass/2026-06-18a - CleanupSA132898DuplicateTracking.sql, dbchanges2/Client_Compass/2026-06-18b - CleanupSA132881DuplicateTracking.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql |
 | [Cost Centers — Unit Locations, numeric-only policy](features/cost-centers.md) | 2.0 | A Compass "cost center" — the value a user picks in commerce and that lands on an order — is **not** a `CostCenters` row. | toga2-commerce/src/pages/Cart/api/CartApi.ts, worker1.5/crons/toga2/compass/import_locations.php, _underscore/Model/Compass/SalesOrder.php, api2/Component/Api/V2/V2.php, dbchanges2/Client_Compass/2026-07-06 - RemoveNonNumericCostCenters.sql |
+| [Compass isFulfillable — Data Quality & the Type-Derived Rule](features/isfulfillable-data-quality-and-type-rule.md) | 2.0 | A **prod-data investigation (2026-08-12, read-only)** into why so many Compass storefront lines still have a dead **Qty Fulfilled** cell. | _underscore/Model/Client/Item.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/backfill_isfulfillable_all_clients.php, toga2-supply/src/pages/Orders/view/OrderView/components/sections/OrderItemsTableSection.tsx |
 | [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, dbchanges2/Client/2026-07-15a - ExcludeFeeItemsFromItemFulfillmentsForSalesOrdersView.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 MITS PO Transmission to Vendors](features/mits-po-transmission-to-vendors.md) | 2.0 | The 1.0 worker cron `2_transmit_mits_purchase_orders_to_vendors.php` transmits Compass PurchaseOrders to their vendors (Office Depot, Strategic Systems, Compass | worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, worker/crons/toga2/compasscanada/workflow/2_transmit_mits_purchase_orders_to_vendors.php, library/app/client/compass.php |

package/knowledge/clients/compass-usa/features/isfulfillable-data-quality-and-type-rule.md

@@ -0,0 +1,187 @@
+---
+title: Compass isFulfillable — Data Quality & the Type-Derived Rule
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-08-12
+owners: ["bala"]
+files:
+  - _underscore/Model/Client/Item.php
+  - library/app/api/toga2.php
+  - worker/crons/toga2/netsuite/backfill_isfulfillable_all_clients.php
+  - toga2-supply/src/pages/Orders/view/OrderView/components/sections/OrderItemsTableSection.tsx
+related:
+  - ../profile.md
+  - ../../compass-canada/profile.md
+  - ../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md
+  - ../../../1.0/apps/library/features/netsuite-item-isfulfillable-sync.md
+  - ../../../1.0/apps/worker/workflows/isfulfillable-multi-client-backfill.md
+---
+
+## Summary
+A **prod-data investigation (2026-08-12, read-only)** into why so many Compass storefront lines still
+have a dead **Qty Fulfilled** cell. Conclusion in one line: the remaining `Items.isFulfillable`
+NULLs are **not a backfill backlog — they are structurally unreachable**, and the values that *are*
+set are partly wrong. This doc records the measured state of `Client_Compass` /
+`Client_CompassCanada`, the evidence for (and against) deriving the flag from item type, the
+**decision** to override NetSuite with a type-derived rule for Compass, and the **write-time guard**
+that decision requires in order to survive the daily NetSuite sync.
+
+No source files were changed and **no migration has been written yet**. All figures below were read
+from **production** on **2026-08-12**.
+
+## Measured state (prod, 2026-08-12)
+- **`Client_Compass`, catalog 1:** **770 NULL / 25 zero / 697 one.**
+- **12,318 Compass order lines have real `ItemFulfillmentItems` but a NULL flag** — the Qty
+  Fulfilled cell is dead on all of them. A further **4,873** lines sit behind `isFulfillable = 0`.
+- **`Client_CompassCanada`: 220 items, 100% NULL.** Canada has **never** been stamped at all, so the
+  Qty Fulfilled cell is dead across the **entire** Canada storefront.
+
+## Why the NULLs cannot be backfilled (structural, not a catch-up gap)
+The flag is born on an **Agilant-catalog source item** during the 1.0 NetSuite item sync
+([Phase 1](../../../1.0/apps/library/features/netsuite-item-isfulfillable-sync.md)) and then
+propagates **up** the `SalesOrderItems`↔`PurchaseOrderItems` chain
+([Phase 2](../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md)). That walk needs
+the Compass PO to have an **Agilant-tier SO behind it** (a `PurchaseOrderItems_SalesOrderItems`
+row). **Vendor-direct POs have none**, so a vendor-fulfilled item can never receive the flag from
+the current pipeline.
+
+Verified in prod `Client_Compass`: **zero** items with `isFulfillable IS NULL` reach the Agilant
+tier, against **52,990** line-level reaches for `isFulfillable = 1` items.
+
+Compass items ordered / reaching the Agilant tier, per vendor:
+
+| Vendor | Ordered | Reaching Agilant tier |
+|---|---|---|
+| OFFICE DEPOT | 497 | 124 |
+| STRATEGIC SYSTEMS | 66 | 0 |
+| FREEDOM GROUPS LLC | 61 | 0 |
+| PRESIDIO | 45 | 0 |
+| COMPASS GROUP | 35 | 0 |
+| ENCOMPASS SUPPLY CHAIN | 2 | 0 |
+
+**Consequence: re-running the multi-client backfill cannot move a single one of these.** Only ODP
+partially routes through Agilant NetSuite.
+
+## The 25 `isFulfillable = 0` Compass items are WRONG — they should be 1
+All 25 are **bundle items**; **14 of them have real fulfillments**. Worst case **`B4NY9UC`**:
+**11,062 order lines and 2,864 fulfillment rows** — the most-shipped laptop in the catalog, with its
+Qty Fulfilled cell **disabled**. NetSuite marks group/kit **headers** `F`, but in TOGa **the header
+IS the line that ships**. This supersedes the earlier assumption (in the Phase 1/Phase 2 docs) that
+the zeros were harmless because values were "uniformly 1".
+
+## Can item type reproduce NetSuite's flag? (evidence)
+**The naive test fails.** "Does this type ever fulfil?" does not separate anything:
+`SERVICES` 119/120 known-fulfillable, `SOFTWARE` 7/7, `FEE` 3/3, while `HARDWARE` fulfils on only
+**26.9%** of lines. `inventoryType = HYBRID` is the **column default** = noise.
+`EntitlementFulfillmentTypes` / `EntitlementFulfillmentMethods` are **EMPTY** in prod.
+
+**The decisive test is the tracking "ride-along":** does a fulfillment row carry **its own** tracking
+number, or does it share one with another line on the same shipment?
+
+| Type | Fulfillment rows | With tracking | Ride-along (shares tracking) |
+|---|---|---|---|
+| itemType `FEE` | 9,639 | 1 (0.0%) | — (0 units) |
+| assetType `FEE` | 10,071 | 22 | **22/22 = 100%** |
+| itemType `SOFTWARE` | — | 129 | **129/129 = 100%** |
+| assetType `MISCELLANEOUS` | — | 385 | **385/385 = 100%** |
+| itemType `SERVICES` | — | 687 | 274 = **39.9%** (413 rows carry their OWN tracking) |
+
+A 100% ride-along rate means the type **never has its own shipment** — a fee/licence line billed
+alongside hardware. `SERVICES` fails that test: 413 service rows genuinely ship on their own.
+
+**⚠ Absence of tracking does NOT prove non-fulfillable.** `DESKTOPS`, `CANTEEN TECHNOLOGY` and
+`VENDING AND OCS ORDERING` all show **0% tracked** yet are physical goods. **Type can only
+DISQUALIFY an item, never confirm one.**
+
+## Decision — the type-derived rule for Compass (2026-08-12)
+Developer's call; it **overrides NetSuite's value**:
+
+```
+isFulfillable = 0  WHERE itemType OR assetType IN
+                   ('FEE','SERVICEFEES','SERVICES','SERVICE','CONSULTING')
+isFulfillable = 1  otherwise
+```
+
+Projected impact:
+- **`Client_Compass`:** **186 → 0** (54 currently NULL + 131 currently **1** + 1 currently 0) and
+  **606 → 1**.
+- **`Client_CompassCanada`:** **13 → 0**, **207 → 1**.
+
+**⚠ Recorded caveat — the SERVICES/CONSULTING half is NOT supported by the evidence.** 413
+`SERVICES` fulfillment rows carry their own tracking, and the rule flips **131 currently-clickable
+items off**. That half **needs product sign-off**. `SOFTWARE` (100% ride-along) is the *stronger*
+candidate on the evidence but was deliberately **left out of scope**.
+
+## ⚠ CRITICAL — a backfill alone will be undone by the daily NetSuite sync
+Phase 1's `getCreateItem` **refreshes `isFulfillable` on EXISTING items** whenever NetSuite's value
+differs from the stored value. NetSuite returns **`T` for service (`NonInvtPart`) items**, so any
+type-derived **0** is **flipped back to 1 on the next sync run**.
+
+Proven from the audit log: Compass items **2382 / 2384 / 2385**
+(`US-IOS-SSC-SHR`, `US-IOS-VENUENEXT`, `US-IOS-VIRTUALMGR` — itemType `SERVICES`, assetType
+`CONSULTING`) were stamped **NULL → 1 on 2026-08-04 13:56:00-01** by `apiId 1`, `userId NULL`,
+inside a **1–2 items/second cron sweep** that began 13:45 and set every item to 1.
+
+**Therefore the rule MUST be enforced at write time** — a `prePut`/`prePost` guard on Items in
+`_Model_Client_Item` — **in addition to** the backfill migration. A migration on its own silently
+reverts within a day.
+
+## Evidence-based alternative signals (if type is not wanted)
+- **`ItemFulfillmentItems`** (via `SalesOrderItems.salesOrderItemId`) = **proven shipped**.
+- **`VendorItems`** (`isActive = 1`) = **procurable from a vendor**.
+
+Tiering the 770 NULL Compass items: **184** have fulfillment history · **286** have an active
+`VendorItems` row · **300** have neither. The frontend gate already requires
+`_qtyFulfilled !== 0`, so **tier-3 items cannot be clicked regardless of the flag**, and can be left
+NULL.
+
+## Where the storefront consumes the flag (+ a hardcode to retire)
+`toga2-supply/src/pages/Orders/view/OrderView/components/sections/OrderItemsTableSection.tsx`,
+`isQtyFulfilledClickable` (~lines 21–30):
+
+```
+String(item?.Items?.isFulfillable) === "1" && Number(item?._qtyFulfilled) !== 0
+```
+
+plus an extra **hardcoded** `hostName === COMPASS && AssetTypes.name === 'FEE' → false`.
+
+- **NULL and 0 behave identically** at this gate.
+- That **FEE hardcode duplicates the proposed data rule** — once the rule lands in the DB it should
+  be **deleted** so the logic lives in one place.
+
+## Compass Canada uses a DIFFERENT type vocabulary
+Canada's `assetTypes` are **title case** (`Equipment`, `Hardware`, `Services`, `Fee`, `Consulting`)
+and its `itemTypes` are a **separate vocabulary** (`LAPTOP`, `MACBOOK`, `MONITORS`, `CABLES`,
+`SERVICE`, `Services`, `CONSULTING`, `SOFTWARE LICENSING`) — it has **no `FEE` or `SERVICEFEES`
+itemType at all**.
+
+Because these tables are `utf8mb4_0900_ai_ci` (**case-insensitive**), the single US-derived
+`IN ('FEE','SERVICEFEES',…)` list **matches Canada's title-case values** — verified against live
+data. **Do not hand-maintain two string lists**, but **do** re-confirm the Canada vocabulary
+separately, since the names genuinely differ and a US list *looks* wrong for Canada.
+
+## Change history
+- 2026-08-12 — Prod read-only investigation of `Items.isFulfillable` across `Client_Compass` /
+  `Client_CompassCanada`. Established that remaining NULLs are **structurally unreachable**
+  (vendor-direct POs have no Agilant-tier SO, so the chain walk has nothing to walk — 0 NULL items
+  reach the Agilant tier vs 52,990 reaches for `=1` items), that the **25 zeros are wrong** (all
+  bundle headers, 14 with real fulfillments, incl. `B4NY9UC` at 11,062 lines / 2,864 fulfillments),
+  and that **Canada is 100% NULL**. Proved item type cannot *confirm* fulfillability but the
+  **tracking ride-along test** cleanly disqualifies fee/software/miscellaneous lines (100%
+  ride-along) while `SERVICES` fails it (39.9%). **Decided** the type-derived rule
+  (`FEE/SERVICEFEES/SERVICES/SERVICE/CONSULTING → 0`, else 1) with the SERVICES/CONSULTING half
+  flagged for product sign-off, and established that it **must** be enforced by a `prePut`/`prePost`
+  guard because the daily sync's existing-item refresh reverts it (audit-log proof: items
+  2382/2384/2385 stamped NULL→1 on 2026-08-04). (bala)
+
+## Related docs
+- [Phase 1 — isFulfillable from NetSuite during item sync (1.0)](../../../1.0/apps/library/features/netsuite-item-isfulfillable-sync.md)
+  — where the value is born and the refresh that reverts overrides.
+- [Phase 2 — isFulfillable propagation up the SO↔PO chain (2.0)](../../../2.0/apps/_underscore/features/fulfillable-item-propagation.md)
+  — the chain walk whose reach is the structural limit described here.
+- [isFulfillable multi-client backfill (worker)](../../../1.0/apps/worker/workflows/isfulfillable-multi-client-backfill.md)
+  — the cron that **cannot** close this gap.

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

@@ -17,7 +17,7 @@ project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-08-11
+updated: 2026-08-12
 owners: [jcardinal, bala, tcox, apeterson, dfranks]
 files: []
 related:
@@ -27,6 +27,7 @@ related:
   - features/mits-sales-order-transmission-alerting.md
   - features/asn-to-item-fulfillment.md
   - features/cost-centers.md
+  - features/isfulfillable-data-quality-and-type-rule.md
   - features/approval-decision-flow.md
   - workflows/cross-kit-bundle-corruption.md
   - workflows/odp-duplicate-po-line-cleanup.md
@@ -134,4 +135,12 @@ separate, related client (see its own profile).
   up the SO↔PO chain to the client-facing Compass item by an api2 interceptor
   ([Phase 2](../../2.0/apps/_underscore/features/fulfillable-item-propagation.md)). Verified on prod
   Compass chains; a one-time July-5+ backfill re-PUTs source items through the same path.
+  **⚠ Prod audit 2026-08-12 — the flag is largely broken for Compass and NO backfill can fix it.**
+  770 NULL / 25 zero / 697 one; **12,318** order lines are really fulfilled but flagged NULL, so
+  their Qty Fulfilled cell is dead. The NULLs are **structurally unreachable** (vendor-direct POs
+  have no Agilant-tier SO to walk up from), and the 25 zeros are **wrong** (bundle headers that do
+  ship — incl. `B4NY9UC`, 11,062 lines). A **type-derived override** was decided and **must** be
+  enforced by a write-time guard, because the daily NetSuite sync reverts it. Evidence, rule,
+  projected impact and caveats:
+  [isFulfillable — Data Quality & the Type-Derived Rule](features/isfulfillable-data-quality-and-type-rule.md).
 - This profile is a starting point; expand as more Compass-specific behavior is captured.

package/knowledge/clients/elite/INDEX.md

@@ -2,9 +2,10 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
+| [Elite — NetSuite → TOGa Supply inbound sync (TRUE-80499 onboarding)](features/netsuite-togasupply-sync.md) | 1.0 | Elite is the 18th client on the shared NetSuite → TOGa Supply importer ([engine](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md)). | worker/crons/toga2/netsuite/sync_togasupply_elite.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/schedules/cron.worker.sync.json, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Elite/PurchaseOrder.php, _underscore/Model/Elite/ItemReceipt.php, dbchanges2/Client_Elite/_modules.txt, test/@srija/Elite Testing/Service Requests/test_sync_togasupply_elite_section.php, test/@srija/Elite Testing/Service Requests/test_diagnose_togasupply_elite.php |
 | [Elite SalesOrder → NetSuite Push (postPost/postPut interceptors → worker2)](features/salesorder-netsuite-push.md) | 2.0 | Elite orders created in Toga are pushed into NetSuite **event-driven**, not on a cron. | _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Elite/ServiceRequest.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Core/2026-08-06a - Service request and sales order payload interceptors.sql |
 | [Elite — Sales Order stage change posts a reply on the TOGa Desk (1.0) ticket](features/salesorder-status-togadesk-reply.md) | 2.0 | When an Elite sales order's **stage** changes, a reply is posted on the originating **TOGa Desk (1.0)** ticket so the requester sees progress where they raised | worker2/Worker/Sync/SalesOrderStatus.php, _underscore/Model/Elite/SalesOrderStatus.php, _underscore/Model/Elite/SalesOrder.php |
 | [Elite — supply2 frontend scope (Inventory + Service Requests, both built)](features/supply2-scope.md) | 2.0 | Scope for onboarding Elite to the `toga2-supply` frontend (host `ELITE`). | toga2-supply/ELITE-CLIENT-TASK-NOTES.md, toga2-supply/src/pages/Orders/view/OrderView/viewModel/FIELDS/ELITE/BASEFIELDS.json, toga2-supply/src/pages/Orders/viewModel/FIELDS/ELITE/BASE.json, toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts, toga2-supply/src/hooks/useFetchData.tsx, toga2-supply/src/components/ui/Toaster.tsx, toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts, toga2-supply/src/pages/Inventory/viewModel/FIELDS/INVENTORYPAGEFIELDS.ts, toga2-supply/src/pages/Inventory/viewModel/index.ts, toga2-supply/src/pages/Inventory/listing/InventoryPage.tsx, toga2-supply/src/pages/Inventory/listing/InventoryRouter.tsx, toga2-supply/src/pages/Inventory/listing/InventorySubTablePage.tsx, toga2-supply/src/utils/resolveClientHostName.ts, toga2-supply/src/utils/convertConstructorColumnTitles.ts, toga2-supply/src/pages/Orders/OrdersPage.tsx, toga2-supply/src/pages/Orders/viewModel/FIELDS/ELITE/BASE.json, toga2-supply/src/pages/Orders/viewModel/useOrdersPageViewModel.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, toga2-supply/src/pages/Orders/view/OrderView/viewModel/useOrderDetailsViewModel.ts, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/renderModalContent.tsx, toga2-supply/src/components/layout/SlideMenu/SlideMenu.tsx, toga2-supply/package.json |
 | [Elite — stale TableView config (11 dead Core.RecordFields across 9 views)](features/supply2-tableview-config-drift.md) | 2.0 | `Client_Elite`'s `TableViewJoins` predate **two** platform bridge-table migrations and still reference **11 deleted `Core.RecordFields` ids (211, 321, 932, 358, | dbchanges2/Client_Elite/, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql |
 | [Elite — raising a Service Request from a TOGa Desk ticket (App_Api_ServiceRequest)](features/togadesk-service-request-intake.md) | 1.0 | An Elite agent raises a **Service Request** from a TOGa Desk (1.0) ticket via a modal. | library/app/api/servicerequest.php, library/app/model/togadesk/ticket.php, togadesk/desk/includes/classes/class.ticket.php, togadesk/desk/template/modals/tickets/serviceRequest.php, togadesk/desk/includes/controllers/modals/tickets/serviceRequest.php, togadesk/desk/includes/controllers/actions/tickets/serviceRequest.php, dbchanges2/Client_Elite/2026-08-11a - EliteServiceRequestTicketUnique.sql, test/@srija/Elite Testing/Service Requests/test_elite_desk_service_request.php |
-| [Elite](profile.md) | 2.0 | Elite is a managed-services client that uses **Freshservice** as their helpdesk platform. | worker2/Worker/Elite.php, worker2/Worker/Sync/ServiceRequest.php, library/app/api/toga2.php, library/app/api/servicerequest.php, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Elite/ServiceRequest.php, togadesk/desk/includes/classes/class.ticket.php |
+| [Elite](profile.md) | 2.0 | Elite is a managed-services client that uses **Freshservice** as their helpdesk platform. | worker2/Worker/Elite.php, worker2/Worker/Sync/ServiceRequest.php, library/app/api/toga2.php, library/app/api/servicerequest.php, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Elite/ServiceRequest.php, togadesk/desk/includes/classes/class.ticket.php, worker/crons/toga2/netsuite/sync_togasupply_elite.php |

package/knowledge/clients/elite/features/netsuite-togasupply-sync.md

@@ -0,0 +1,141 @@
+---
+title: "Elite — NetSuite → TOGa Supply inbound sync (TRUE-80499 onboarding)"
+framework: "1.0"
+repo: worker
+project: Worker
+client: elite
+type: client-feature
+status: active
+updated: 2026-08-12
+owners: ["snaredla"]
+files:
+  - worker/crons/toga2/netsuite/sync_togasupply_elite.php
+  - worker/crons/toga2/netsuite/common_sync_togasupply.php
+  - worker/schedules/cron.worker.sync.json
+  - _underscore/Model/Elite/SalesOrder.php
+  - _underscore/Model/Elite/PurchaseOrder.php
+  - _underscore/Model/Elite/ItemReceipt.php
+  - dbchanges2/Client_Elite/_modules.txt
+  - test/@srija/Elite Testing/Service Requests/test_sync_togasupply_elite_section.php
+  - test/@srija/Elite Testing/Service Requests/test_diagnose_togasupply_elite.php
+related:
+  - ../profile.md
+  - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
+  - ../../../1.0/apps/worker/workflows/onboarding-client-to-netsuite-togasupply-sync.md
+  - ./salesorder-netsuite-push.md
+  - ./supply2-scope.md
+  - ../../growrk/features/units-netsuite-custom-fields.md
+---
+
+## Summary
+
+Elite is the 18th client on the shared NetSuite → TOGa Supply importer
+([engine](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md)). This doc records
+what is **Elite-specific**; everything about how the engine works, and the two provisioning gaps this
+onboarding discovered, lives in the engine and
+[onboarding workflow](../../../1.0/apps/worker/workflows/onboarding-client-to-netsuite-togasupply-sync.md)
+docs.
+
+**Direction matters:** this is the **inbound** half (NetSuite → TOGa). The **outbound** push of Elite
+orders *into* NetSuite is a separate, event-driven path — see
+[salesorder-netsuite-push](./salesorder-netsuite-push.md). Nothing in this cron ever writes to
+NetSuite.
+
+**Backfill result (2026-08, April 2024 → Aug 2026, ~90 minutes):** 257 SalesOrders (0 missing a
+NetSuite id), 234 PurchaseOrders, 201 ItemFulfillments, 29 ItemReceipts, 2 InventoryAdjustments,
+153 Items, 229 Units, 1042 Contacts, 806 Addresses.
+
+## What was built
+
+| Piece | Detail |
+|---|---|
+| **Wrapper** | `worker/crons/toga2/netsuite/sync_togasupply_elite.php` — `isParentCustomer` **false**, NetSuite customer internal id **36443**, end-user-customer custom field **3149** |
+| **Schedule** | `cron.worker.sync.json`, `*/5 * * * *`, `active: 1` |
+| **Client models** | 18 new `_underscore/Model/Elite/*.php` trait models (see below) |
+| **Schema** | `dbchanges2/Client_Elite/_modules.txt` opts into `_modules/netsuite` |
+| **Warehouse locations** | `2026-08-05b` (NetSuite **196** "Elite"/Chicago) and `2026-08-06d` (NetSuite **5** "New York") — both confirmed to carry real Elite inventory-adjustment activity before seeding |
+| **Vendor + ACL fixes** | `2026-08-06e - EliteAgilantVendor.sql`, `2026-08-06a - EliteNetsuiteCustomFieldAcl.sql` — the two module gaps, [written up in the workflow](../../../1.0/apps/worker/workflows/onboarding-client-to-netsuite-togasupply-sync.md) |
+
+### The 18 trait models are pure convention — and fail SILENTLY
+
+Each is only `class _Model_Elite_X extends _Model_Client_X { use _Trait_Netsuite_X; }`:
+Country, Customer, InventoryAdjustment, Invoice, Item, ItemFulfillment, ItemFulfillmentItemUnit,
+ItemFulfillmentStage, ItemReceipt, Location, PaymentTerm, PurchaseOrder, SalesOrder, SalesOrderItem,
+SalesOrderStage, ShippingMethod, Subsidiary, Vendor.
+
+Resolution is **pure class-name string substitution off the JWT client slug** —
+`api2/Component/Api/V2/V2.php:2878-2886` reads `jwtPayload.id.client.slug` and does
+`str_replace('_Model_Client_', '_Model_Elite_', …)` then `class_exists()`; the same block repeats at
+:3148, :3744 and :4177 for nested/sort paths. **If `class_exists` fails, it falls back to the base
+`_Model_Client_X` with no error, no log, and a 200 response** — the `c_netsuite*` fields simply are
+not there. So a typo'd filename or class name presents as "the sync ran and imported nothing useful",
+never as a failure.
+
+The mirror-image trap is the one that bit GroWrk: once the model **does** resolve, every `c_` field
+the trait declares must exist as a column, a `CustomRecordFields` row **and** an ACL grant, or reads
+500/403 — see [GroWrk NetSuite-module custom fields](../../growrk/features/units-netsuite-custom-fields.md).
+
+### Elite-only wrapper deviations
+
+- **`MAX_TIME_WINDOW_TO_FETCH_FROM_NETSUITE_SECONDS = 2592000` (30 days)**, vs. the 5-day default the
+  other 17 wrappers inherit — Elite is backfilling from 2024 and 5-day windows on a 5-minute cron were
+  too slow. This is only possible because the shared engine now `define()`s the cap instead of
+  `const`-ing it. **Reduce it to the default once the backfill is caught up.**
+- **`IS_ENABLED_INTEGRATION_INVOICES = false` — TEMPORARY.** The invoice section scans the whole
+  NetSuite transaction table per window, kept running out of time, and **starved the item-receipt and
+  item-fulfillment sections that follow it** — which are what `_qtyOnHand` derives from. Re-enable
+  once inventory has caught up. (Note the invoice section is also capped at `now − 86400s` by design,
+  so it always trails.)
+- **`MIN_DATETIME_TO_CHECK_FOR_NETSUITE_DATA = '2018-01-01'`**, with the real start controlled by the
+  seeded `Parameters` cursors.
+
+## Gotchas / known issues
+
+- **⚠ Two files named `sync_togasupply_elite.php`, both scheduled.**
+  `worker/crons/toga2/netsuite/sync_togasupply_elite.php` (`*/5`) is **this** supply importer;
+  `worker/crons/toga2/elite/sync_togasupply_elite.php` (`*/2`) is the older
+  `syncWithToga`/`syncWithTogadesk` desk bridge with its own parameter keys. They coexist harmlessly
+  but **confirm the folder before editing** — this is the generic name collision the engine doc warns
+  about, now real for Elite.
+- **⚠ `Client_Elite` has TWO active `Apis` rows** (Agilant `id 1`, Elite `id 2`). `getClientContext()`
+  does `LIMIT 1` with **no `ORDER BY`**, so a worker can authenticate as the wrong client. Not yet
+  fixed; be explicit about which api uuid/secret you pass.
+- **⚠ `Client_Elite.Countries` needs a cleanup migration.** Three rows were auto-created by the sync
+  from the NetSuite strings before `Countries` was pre-seeded, with malformed codes/names:
+  `_unitedKingdom` → `_united Kingdom` / `_i`, `_canada` → `_canada` / `_C`, `_australia` →
+  `_australia` / `_A`. Fix `code`/`name` to `GB`/`CA`/`AU` **without touching `c_netsuiteCountry`** —
+  that string is the sync's match key and must keep NetSuite's exact value (leading underscore
+  included). Mechanics in the
+  [engine doc](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
+  This matters for Elite specifically because **Elite ships internationally** (see the shipping
+  decision on the [profile](../profile.md)).
+- **⚠ The four migrations named above (`2026-08-05b`, `2026-08-06a`, `2026-08-06d`, `2026-08-06e`) are
+  NOT in the `dbchanges2` checkout** — absent from `_main`'s working tree and from
+  `origin/TRUE-80499` as of 2026-08-12. They may be uncommitted on another machine/branch. Exactly the
+  GroWrk situation ("production is ahead of the repo"): until they are committed, the next
+  environment or client provisioned from `dbchanges2` re-creates this drift. **Do not re-write them
+  from memory — find the branch.**
+- **`Units.locationId` is NULL for all 229 Elite Units.** The sync never populates it; transaction
+  location lives on `InventoryAdjustmentItems.locationId` (populated: 6 rows at NetSuite 196, 1 at 5).
+  Any Elite inventory table view must read location from the transaction items.
+- **Sales order 169441 was missing from the first backfill** (NetSuite id 4624062, 2024-04-15,
+  customer PO `BEGGS/04152024/…`) because its window ran ~15 minutes before the vendor fix. It is the
+  worked example for the engine's cursor-advances-past-a-failed-record behaviour — recovered by
+  rewinding `NETSUITE_LAST_SYNC_DATETIME_SALES_ORDERS`.
+
+## Change history
+
+- 2026-08-12 — TRUE-80499: **onboarded Elite to the NetSuite → TOGa Supply importer.** Built the
+  wrapper (customer 36443, `isParentCustomer` false, 30-day window, invoices temporarily disabled),
+  the schedule entry, 18 `_Model_Elite_*` netsuite trait models, the `_modules/netsuite` opt-in, and
+  the two warehouse Locations (NetSuite 196 Chicago, 5 New York). Fixed the two module gaps that
+  blocked it (missing shared "Agilant" `Vendors` row → 400 `EV-12` on every customer-PO order, 191
+  Sentry events/day, PurchaseOrders 0 → 234; and 27 custom fields with 0 ACL grants → 403 `EV-2`) —
+  both generalised into the
+  [onboarding workflow](../../../1.0/apps/worker/workflows/onboarding-client-to-netsuite-togasupply-sync.md).
+  Full backfill April 2024 → Aug 2026 completed in ~90 minutes (257 SalesOrders / 234 PurchaseOrders /
+  201 ItemFulfillments / 29 ItemReceipts / 153 Items / 229 Units / 1042 Contacts / 806 Addresses).
+  Recorded the silent `class_exists` fallback in client-model resolution, the duplicate
+  `sync_togasupply_elite.php` filename across two integrations, the two active `Apis` rows vs.
+  `getClientContext()`'s unordered `LIMIT 1`, the `Countries` cleanup still owed, and that the four
+  dbchanges2 migrations are not in the repo checkout. (snaredla)

package/knowledge/clients/elite/features/togadesk-service-request-intake.md

@@ -154,6 +154,16 @@ wrong-country address.
 select2 state list kept emptying the dropdown — the file's own comment records this. The
 server-side pair check is the guard; the modal stays as-is.
 
+### …and that is the ONLY address rule Elite wants (confirmed 2026-08-12)
+
+Elite confirmed (via Bala): **no address validation — Elite ships internationally.** So the modal
+must **not** enforce US state/postal formats and **must not** copy Prudential's `_unitedStates`
+hardcoding. The country/state **pair** check above stays, because it is a correctness guard (a 2.0
+`Addresses` row derives its country from its state), not a US-format rule — and the country must still
+resolve to a real `Countries` row for the downstream NetSuite push. Elite also **dictates the shipping
+method on the Sales Order: FedEx only.** Both rules and their reference orders are on the
+[Elite profile](../profile.md#shipping-rules-confirmed-with-elite-by-bala-2026-08-12).
+
 ## Test harness
 
 `test/@srija/Elite Testing/Service Requests/test_elite_desk_service_request.php` (PHP **7.2**)
@@ -204,6 +214,12 @@ them, so it proves everything *after* the permission check, not the check itself
 
 ## Change history
 
+- 2026-08-12 (shipping rules) — Recorded Elite's confirmed shipping decisions (via Bala): the
+  **shipping method is dictated on the Sales Order and is FedEx only**, and there is deliberately
+  **no address validation** because Elite ships internationally — so the modal must not enforce US
+  state/postal formats and must not reuse Prudential's `_unitedStates` hardcoding. The country/state
+  pair check stays (correctness, not US-format), and the country must still resolve to a `Countries`
+  row for the NetSuite push. (snaredla)
 - 2026-08-12 (later pass) — Recorded the **button gate** itself
   (`isEliteServiceRequestTicket()`: client 163 + department 299 + custom field 88 = `Service
   Request`; the button **replaces** "New Part Request" on those tickets, and the 2.0 uuid comes from

package/knowledge/clients/elite/profile.md

@@ -2,6 +2,7 @@
 title: Elite
 framework: "2.0"
 apps:
+  - worker
   - worker2
   - library
   - toga2-supply
@@ -24,7 +25,9 @@ files:
   - _underscore/Model/Elite/SalesOrder.php
   - _underscore/Model/Elite/ServiceRequest.php
   - togadesk/desk/includes/classes/class.ticket.php
+  - worker/crons/toga2/netsuite/sync_togasupply_elite.php
 related:
+  - features/netsuite-togasupply-sync.md
   - 2.0/apps/worker2/features/elite-freshservice-sync.md
   - 1.0/apps/library/features/elite-freshservice-sync.md
   - features/supply2-scope.md
@@ -49,6 +52,27 @@ on beta as of 2026-08-10; see [supply2-scope](features/supply2-scope.md). The ba
 dbchanges2 **PR #454** (TRUE-80499, snaredla24, 2026-08-05) added the **netsuite** module to
 `Client_Elite/_modules.txt` — the supply-chain schema layer is arriving.
 
+**Elite is live on the inbound NetSuite → TOGa Supply sync as of 2026-08-12 (TRUE-80499).** A
+`*/5` worker cron backfilled April 2024 → Aug 2026 in ~90 minutes (257 sales orders, 234 purchase
+orders, 201 item fulfillments, 153 items, 229 units) — this is what adds **`worker`** (1.0) to
+Elite's app scope. Elite-specific config, the still-owed `Countries` cleanup, and the two active
+`Apis` rows hazard are in [netsuite-togasupply-sync](features/netsuite-togasupply-sync.md).
+
+## Shipping rules (confirmed with Elite by Bala, 2026-08-12)
+
+Two client rules that constrain every order-creation surface (the desk Service Request modal, the
+supply2 order forms, and the NetSuite push):
+
+- **Elite dictates the shipping method on the Sales Order, and it is FedEx only** — the shipping-method
+  field must accept FedEx carrier values only.
+- **No address validation.** Elite ships **internationally**, so **do not port Prudential's
+  `_unitedStates` hardcoding** and the SR modal must **not** enforce US state/postal formats.
+  Reference sales orders: **285264, 285379, 285346**.
+
+The country still has to resolve to a real `Countries` row for the NetSuite push to succeed — "no
+address validation" means no US-format enforcement, not "any string goes." Full reasoning is recorded
+in `test/@srija/DOCS/ELITE/ELITE_SR_PLAN_BALA.md` and `ELITE_SR_PLAN_COMBINED.md`.
+
 Elite's service-request data model: `ServiceRequests` is the record the `service-requests` table
 view is built on (joining Tickets / Customers / ServiceRequestTypes / SalesOrders, with
 `SalesOrders.serviceRequestId = ServiceRequests.id`). **That relationship is 1:N, not 1:1**

package/package.json

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