toga-ai 1.0.554 → 1.0.555

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

@@ -6,8 +6,8 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-05
-owners: ["dfranks", "bala", "jcardinal"]
+updated: 2026-08-11
+owners: ["dfranks", "bala", "jcardinal", "mhammontree"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
   - worker/crons/toga2/netsuite/sync_togasupply_canon.php
@@ -149,6 +149,14 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
 
 ## Gotchas / known issues
 
+- **⚠ 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
+  `App_Api_Toga2::syncItemReceiptFromNetsuite`
+  (`worker/crons/toga2/netsuite/common_sync_togasupply.php:903`) from
+  `worker/crons/toga2/netsuite/sync_togasupply_growrk.php:42` — **288 events/day** on 2026-08-07/08/09.
+  This is the **1.0 stack** (`worker` + `library`) and was deliberately out of scope for TRUE-80824.
+  **Needs its own ticket.**
 - **Split history:** all per-client wrappers were carved out of a single `CLIENT_CONFIGURATION`
   array in `sync_togasupply.php` by commit **778a3f1f** (2026-04-17). The original 15-client
   array is archived at `worker/test/@dave/netsuite_togasupply_original_clients.php`.
@@ -237,6 +245,10 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
 
 ## Change history
 
+- 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).
+  1.0 stack, out of scope for that ticket; needs its own. (mhammontree)
 - 2026-08-05 — Documented that `syncItemFulfillmentFromNetsuite` is now a **full reconcile** like
   `syncSalesOrderFromNetsuite`: updates IF items/units + serial/`assetTag`/`macAddress`
   (never blanking), maintains **all three** tracking bridges (317/318/319), and **prunes**

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

@@ -10,7 +10,7 @@
 | [_ApiRequest — JSON encode/decode & api-logging behavior](features/apirequest-json-content-type.md) | `_ApiRequest` is the 2.0 outbound HTTP client. | _underscore/ApiRequest.php |
 | [Assortment Name Translation (AssortmentTranslations sidecar)](features/assortment-name-translation.md) | Serves Assortment (product-grouping) **names** in multiple languages by adding a per-language **sidecar** table `AssortmentTranslations`, reusing the platform's | _underscore/Model/Client/AssortmentTranslation.php, dbchanges2/Client/2026-06-26a - AssortmentTranslations.sql, dbchanges2/Core/2026-06-26a - AssortmentTranslationsRecord.sql, dbchanges2/Client/2026-06-26b - AssortmentTranslationsAcl.sql |
 | [Asynchronous Query Execution (writes-only, via Worker)](features/async-query-execution.md) | `_Query` can run a **write** query asynchronously so a long/slow write does not hold a request-scoped DB connection open long enough to hit **"MySQL server has | _underscore/Query.php, worker2/Worker/Infrastructure/Database.php, worker2/Worker/Team/Transcripts.php |
-| [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
+| [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | test/@Mark/true-80824-fedex-inflate-test.php, dbchanges2/Client_Growrk/2026-08-10e - GrowrkUpsServiceMethodCodes.sql, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [Running 2.0 code from a bare CLI script (bootstrap + transactions)](features/cli-script-bootstrap.md) | A throwaway CLI script (a data check, a backfill dry-run, a render harness) that wants the real 2.0 framework — `_Model`, `_Query`, `_Database` — is **not** the | _underscore/Database.php, _underscore/Environment.php, api2/Initialize.php |
 | [_Cloud S3 helpers (copy / get / delete / list)](features/cloud-s3-helpers.md) | `_Cloud` centralizes AWS SDK S3 usage for the 2.0 stack so the `S3Client` never leaks into workers or app code. | _underscore/Cloud.php |
 | [_Component_*/_Model_* project-namespace registration (autoloader) & backslash-qualify traps](features/component-model-namespace-registration.md) | Every **project-local** `_Component_*` and `_Model_*` class in a 2.0 app **must declare the project namespace** at the top of the file: ```php namespace <NAMESP | _underscore/Loader.php, worker2/_.php, api2/_.php, worker2/Component/Forecast/Db/Db.php, worker2/Component/Forecast/SaleImport/SaleImport.php, worker2/Component/Api/Oneuptime/Oneuptime.php, api2/Component/Api/Netsuite/Netsuite.php, _underscore/Component/Api/Paypal/Paypal.php |
@@ -27,6 +27,7 @@
 | [_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 |
 | [_Model::save() vs raw _Query — no atomic conditional update](features/model-save-vs-query-atomic-update.md) | `_Model::save()` is a plain load-then-write ORM primitive and **cannot express an atomic conditional update** (an optimistic-concurrency / row-claim guard such | _underscore/Model.php, _underscore/Query.php, _underscore/Model/Rate/Subscription.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php |
+| [NetSuite Sales Order sync — ship-to address, phone, and PO reference sourcing](features/netsuite-salesorder-address-phone-sync.md) | `_Trait_Netsuite_SalesOrder` is the **shared** sales-order importer composed into **22 client models** (every client on the dbchanges2 `netsuite` module). | _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Model.php, dbchanges2/_modules/netsuite/2026-08-10a - AddressPhoneNumberApiRoleAcl.sql |
 | [Legacy page meta (Page::meta) & context-scoped ClientRecordFieldSettings](features/page-meta-context-field-settings.md) | `_Model_Core_Page::meta()` is the **legacy** page-meta resolver behind `GET /pages/meta?slug=<slug>` — still the live path for `toga2-supply` and other pre-Surf | _underscore/Model/Core/Page.php |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/Query.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php, api2/Controller/Index.php |
 | [Persona Name Translation (PersonaTranslations sidecar)](features/persona-name-translation.md) | Serves Persona **names** in multiple languages by adding a per-language **sidecar** table `PersonaTranslations`, reusing the platform's existing metadata-driven | _underscore/Model/Client/PersonaTranslation.php, dbchanges2/Client/2026-07-22b - PersonaTranslations.sql, dbchanges2/Core/2026-07-22a - PersonaTranslationsRecord.sql, dbchanges2/Client/2026-07-22c - PersonaTranslationsAcl.sql, dbchanges2/Client_CompassCanada/2026-07-22 - PersonaTranslationsFrench.sql, toga2-commerce/src/pages/Account/view/MySettingsView.tsx |

package/knowledge/2.0/apps/_underscore/features/carrier-shipping-labels.md

@@ -6,9 +6,11 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-03
+updated: 2026-08-11
 owners: [mhammontree]
 files:
+  - test/@Mark/true-80824-fedex-inflate-test.php
+  - dbchanges2/Client_Growrk/2026-08-10e - GrowrkUpsServiceMethodCodes.sql
   - _underscore/Model/Client/ItemFulfillment.php
   - _underscore/Model/Client/TrackingNumber.php
   - _underscore/Model/Client/ItemFulfillments/TrackingNumber.php
@@ -229,6 +231,49 @@ same type**.
 `TN` was chosen over `ON` (Dealer Order Number) precisely **because UPS prints the code's meaning** —
 "Dealer Order Number" would be misleading next to a sales-order number.
 
+## FedEx returns GZIP-ENCODED error bodies — `inflateIfCompressed()` (implemented 2026-08-11, TRUE-80824)
+
+FedEx (or an edge/WAF in front of it) returned a **gzip-encoded HTTP 400**. `_ApiRequest` sets **no
+`CURLOPT_ENCODING`**, so curl hands back **compressed bytes**, `json_decode` returns `null`, and
+`describeShipmentError()` fell through to its raw-body fallback — surfacing
+`"FedEx returned HTTP 400 in an unrecognized format: \x1f\x8b\b…"`. Compounding it, the ship call runs
+**`$api->setLogging(false)`** (deliberate — a successful ship response carries the full base64 label,
+megabytes), so **there is NO outbound log row** to recover the body from. **This differs from UPS**,
+whose real errors *are* in the client-logs `Api` table (`direction = OUT`, `hostname LIKE '%ups.com%'`).
+
+`Fedex.php` gained a private **`inflateIfCompressed()`**, applied to **BOTH the error and the success
+paths** (a compressed `200` would otherwise become "Invalid shipment response"):
+
+1. **gzip magic (`\x1f\x8b`) → `gzdecode()`**, falling back to `gzinflate(substr($payload, 10))` for a
+   truncated stream.
+2. Otherwise — **and ONLY when the payload is not valid UTF-8** — try `gzuncompress()` then
+   `gzinflate()`; **first non-empty result wins**.
+
+**Three encodings need three functions:** gzip = `gzdecode`, **raw** deflate = `gzinflate`, **zlib**
+deflate = `gzuncompress`. Both `gzdecode` and `gzinflate` return `false` on zlib-wrapped deflate —
+which is what most servers actually send for `Content-Encoding: deflate`.
+
+### ⚠ THE UTF-8 GUARD IS LOAD-BEARING — DO NOT REMOVE IT
+
+zlib and raw deflate **cannot be detected reliably** (zlib's CMF/FLG pair varies with window size; raw
+deflate has **no header at all**), so they can only be *attempted* — and attempting them on a legible
+body is **destructive**. Measured by **fuzzing 100,000 valid-UTF-8 bodies** (JSON error envelopes,
+HTML error pages, short printable ASCII): **`gzinflate()` returned a non-false, non-empty result on
+257 of them (~1 in 390)**, turning one 64-byte JSON error into **403 bytes of binary junk**. So a
+**"first non-empty result wins" rule does NOT make it safe.** Every such input is valid UTF-8 and
+every garbage output is not, so a single **`preg_match('//u', $payload)`** check removes the entire
+class of false positives. **CodeRabbit asked twice to remove this guard; it was rejected on this
+evidence.**
+
+**Regression coverage:** `test/@Mark/true-80824-fedex-inflate-test.php` — 18 cases, drives the private
+method **by reflection against the real class file** (no DB, no network, no bootstrap; see the
+[static no-DB regression harness](../../../1.0/apps/test/features/static-no-db-regression-harness.md)),
+including **4 fuzz-discovered `fp:` cases whose only job is to fail if the UTF-8 guard is ever removed**.
+
+**Still open (recommended, not done):** setting **`CURLOPT_ENCODING` in `_ApiRequest`** would fix this
+class for **every** integration, but that is the framework's shared HTTP client and needs its own
+review. **The UPS client has the same latent gap.**
+
 ## `FIELD_STORAGE` mechanics (reference)
 
 `Model.php` handles storage fields separately from regular columns (write loop ~line
@@ -301,7 +346,11 @@ still discards the unsaved in-memory value.
 - UPS `AddressLine` max 35 chars/line; send an array of trimmed lines (FedEx already
   does), not `line1 . ' ' . line2`.
 - `ShippingMethods.code` is carrier-scoped: UPS numeric (`03` Ground, `01` Next Day
-  Air), FedEx strings (`FEDEX_GROUND`). Empty code → UPS error 120500.
+  Air), FedEx strings (`FEDEX_GROUND`). Empty code → UPS error 120500. **⚠ In production this column
+  is empty for most clients** (2026-08-11: Elite 0/6, Quad 0/12, Rate 0/4, Compass 1/23 — and that one
+  is an invalid `'GND'`; GroWrk ids 3/4 were fixed by
+  `Client_Growrk/2026-08-10e - GrowrkUpsServiceMethodCodes.sql`). Because the TOGa Supply dropdown
+  renders `name`, not `code`, **the UI shows no signal** — check the data before debugging the code.
 - Serialized-inventory assignment fails ("Invalid issueinventorynumber reference key")
   when the lookup isn't location-scoped and the SO has no Warehouse Location —
   recommended: always scope `getInventoryNumberFromSerialNumber` by location.
@@ -367,6 +416,20 @@ still discards the unsaved in-memory value.
   bill) — expect a hard error rather than a silently-wrong bill in those cases.
 
 ## Change history
+- 2026-08-11 — TRUE-80824: **made FedEx carrier rejection reasons readable.** FedEx returned a
+  **gzip-encoded HTTP 400** and `_ApiRequest` sets no `CURLOPT_ENCODING`, so `json_decode` saw
+  compressed bytes and `describeShipmentError()` printed `\x1f\x8b…`; with `setLogging(false)` on the
+  ship call there is no log row to recover the body from (unlike UPS, whose errors are in the
+  client-logs `Api` table). Added `inflateIfCompressed()` on **both** the error and success paths
+  (gzip magic → `gzdecode`, fallback `gzinflate(substr($payload,10))`; otherwise, **only when the
+  payload is not valid UTF-8**, `gzuncompress` then `gzinflate`, first non-empty wins). Documented that
+  the **UTF-8 guard is load-bearing**: fuzzing 100k valid-UTF-8 bodies had `gzinflate()` return
+  non-false, non-empty output on **257** of them (~1 in 390), so "first non-empty wins" alone is
+  unsafe — `preg_match('//u', …)` removes the class (CodeRabbit's twice-requested removal was rejected
+  on this evidence). Regression: `test/@Mark/true-80824-fedex-inflate-test.php`, 18 cases by reflection
+  incl. 4 fuzz-derived guard cases. Also recorded the production `ShippingMethods.code` data gap
+  across clients. **Open:** set `CURLOPT_ENCODING` in `_ApiRequest` for all integrations — the UPS
+  client has the same latent gap. (mhammontree)
 - 2026-08-03 — TRUE-80494: **wired Reference 1 / Reference 2 through to the carrier so they PRINT on
   the label** — `ShipmentRequest` gained `$referenceString2`, `upsShipmentApi`/`fedexShipmentApi`
   gained optional `$reference1`/`$reference2` (transient query-string params, **zero dbchanges2

package/knowledge/2.0/apps/_underscore/features/netsuite-salesorder-address-phone-sync.md

@@ -0,0 +1,102 @@
+---
+title: NetSuite Sales Order sync — ship-to address, phone, and PO reference sourcing
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-08-11
+owners: ["mhammontree"]
+files:
+  - _underscore/Trait/Netsuite/SalesOrder.php
+  - _underscore/Model.php
+  - dbchanges2/_modules/netsuite/2026-08-10a - AddressPhoneNumberApiRoleAcl.sql
+related:
+  - acl-permission-chain.md
+  - address-uniqueness-normalization.md
+  - carrier-shipping-labels.md
+  - ../../toga2-supply/features/fulfill-and-ship.md
+  - ../../api2/features/record-scripts.md
+---
+
+## Summary
+
+`_Trait_Netsuite_SalesOrder` is the **shared** sales-order importer composed into **22 client models**
+(every client on the dbchanges2 `netsuite` module). It writes the sales order, its ship-to
+`Addresses` record, and the linked purchase order. This doc records where each user-visible value
+comes from and the four traps that make a change here risky, because **anything changed in this trait
+changes behaviour for all 22 clients at once**.
+
+## Where the values come from (confirmed against production, 2026-08-11)
+
+| Value | Source |
+|---|---|
+| Sales order # (TOGa Supply "Reference 1") | `SalesOrders.number` |
+| Purchase order # ("Reference 2") | NetSuite **`otherRefNum`**, stored as a **`PurchaseOrders` record linked through the `PurchaseOrders_SalesOrders` bridge** |
+| Ship-to phone | the NetSuite **shipping address's `addrPhone`** → `Addresses.phoneNumber` |
+
+**⚠ Reference 2 is NOT `SalesOrders.customerPurchaseOrder`.** That column is only ~**59%** populated
+(and was NULL on the order tested), while the **bridge covers 12,643 of 12,658** orders. Resolve the
+PO through the bridge, not the column.
+
+## ⚠ Four traps when writing a field on this shared trait
+
+1. **Normalise a phone with `_String::cleanPhoneNumber()` on the way INTO the payload.**
+   `Addresses.phoneNumber` is **`FIELD_CHAR_PHONE`**, and `_Model` runs **every write** through that
+   same function (`Model.php` ~584), reformatting a 10-digit number to `"(XXX) XXX-XXXX"`. Sending
+   NetSuite's raw string therefore **stores a different value than was sent**, making the
+   change-detection comparison **permanently unequal** and re-`PUT`ting the address on **every sync,
+   for every client on the trait**. Verified idempotent/stable across raw, dashed, dotted, leading-1,
+   extension, short and empty inputs.
+2. **Add the field to the change-detection `if` comparison, not only to the payload.** An existing
+   address otherwise takes the **"no changes necessary"** branch and the value is never written —
+   which makes the fix look like a **no-op**.
+3. **`$api->internalApiRequest()` runs on the SAME authenticated session as the outer call, so ACL
+   applies** — and the NetSuite sync authenticates as **`roleId` 3 ("API"**; roles are 1 = Base,
+   2 = Developer, 3 = API, 4 = Public). `Addresses.phoneNumber` is **`Core.RecordFields` id 990** and
+   had **no role-3 grant on 20 of the 22** netsuite-module clients (Compass and Prudential already had
+   it). Without the grant you get either an **EV-9 write failure** or a **silently dropped field** —
+   and the silent case recreates the infinite address re-`PUT` from trap 1. Hence a **MODULE-scoped**
+   migration: `_modules/netsuite/2026-08-10a - AddressPhoneNumberApiRoleAcl.sql`.
+4. **The ACL migration MUST be applied BEFORE the `_underscore` deploy.** Deploying the code first
+   makes the sync write `Addresses.phoneNumber` as the API role with no grant — EV-9 failures or an
+   address re-`PUT` on every sync across all 22 clients. (Note the usual *backend-first* rule for the
+   frontend did **not** apply here: no new RecordScript parameter was added, so toga2-supply had no
+   ordering constraint.)
+
+## Data reality — phones are absent, not wrong
+
+Before this change, **only 1 of 12,504** GroWrk ship-to addresses on a sales order had a phone number.
+The few populated addresses elsewhere hold junk (`1234567890`, `(123) 456-7890`), and some **addressee**
+fields have phone numbers jammed into them.
+
+**Decision (Mark): no backfill.** The phone only appears on sales orders that **re-sync from NetSuite
+after deploy**, so an existing order will never show one — **a blank phone is not evidence of a failed
+deploy.** Expect a **one-time burst of address `PUT`s** as phones converge on the first sync; that is
+intended, not a fault.
+
+## Gotchas / known issues
+
+- **Read grants were already in place** for the values this change consumes — `sales-orders.number`
+  (`RecordFields` 49), `purchase-orders.number` (87) and the bridge (1891/1892) on roles **1 and 3** —
+  so no migration was needed for the reads. Always check per-role grants for **both** directions
+  separately; a read grant is not a write grant.
+- **A `FIELD_CHAR_PHONE` (or any normalising field type) breaks naive change detection.** Compare the
+  **normalised** form on both sides, or the record is rewritten forever. This applies to any 2.0 field
+  whose type transforms the value on write.
+- **22 clients share this trait.** Grep the `use _Trait_Netsuite_SalesOrder` composition list before
+  assuming a change is client-scoped; a "small GroWrk fix" here is a platform change.
+
+## Change history
+
+- 2026-08-11 — TRUE-80824: created. Prefilled TOGa Supply's Reference 1 / Reference 2 / Phone # from
+  NetSuite by sourcing `SalesOrders.number`, the bridge-linked purchase order (`otherRefNum` — **not**
+  `customerPurchaseOrder`, ~59% populated vs the bridge's 12,643/12,658), and the shipping address's
+  `addrPhone`. Recorded the four traps: `cleanPhoneNumber()` normalisation on the way in (because
+  `FIELD_CHAR_PHONE` reformats on write and would otherwise re-`PUT` every address on every sync for
+  all 22 clients), adding the field to the change-detection comparison as well as the payload,
+  `internalApiRequest()` inheriting the caller's session so the sync's **roleId 3 ("API")** needs an
+  explicit grant on `Core.RecordFields` 990 (missing on 20 of 22 clients → module-scoped migration
+  `_modules/netsuite/2026-08-10a`), and the hard **migration-before-deploy** ordering constraint.
+  Decision: **no backfill** — a blank phone on an old order is expected. (mhammontree)

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

@@ -5,6 +5,6 @@
 | [Database Changes (dbchanges2) Repository Architecture](architecture.md) | `dbchanges2` is the **schema-migration / SQL change-set repository** for the entire 2.0 platform. | Core/, Client/, Client_<Tenant>/, Logs/, Logs_Client/, _modules/ |
 | [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Core/2026-07-20a - Update - HideAdminNotesSectionByDefault.sql, dbchanges2/Core/2026-07-20b - Update - NotesSectionFieldElements.sql, dbchanges2/Client_Compass/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_Compass/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_Quad/2026-07-20a - NotesSectionFieldsOverride.sql, dbchanges2/Core/2026-07-20c - Update - VendorItemsToggleSurfaceSeed.sql, dbchanges2/Client_Compass/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Core/2026-07-20e - RestoreApproveDenyRowActions.sql, dbchanges2/Client_Compass/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Core/2026-07-17 - README - RUN ORDER.md, dbchanges2/Client_Compass/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Compass/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_CompassCanada/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_Quad/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Quad/2026-07-21b - SalesOrderApproveDisabledTooltipTranslation.sql, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Core/2026-07-23a - PoNumberDetailFieldValueKey.sql |
 | [2.0 New-Client Onboarding (manual process)](workflows/client-onboarding.md) | > **A local browser wizard now automates this.** Steps 2–9 below (create DBs, generate Core/API > inserts, append to `Clients_Db.txt`) — plus the dbchanges2 bla | Client/, Client_<Tenant>/, Core/, Logs_Client/ |
-| [Auditing a client DB that drifted from its models (partially applied module migration)](workflows/client-schema-drift-audit.md) | A recurring 2.0 failure mode: **one client's database drifts from what the PHP models declare**, usually because a `_modules/<module>/` migration was applied to | dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Growrk/2026-08-10 - GrowrkUnitInventoryFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10b - GrowrkUnitItemDescriptionAcl.sql, dbchanges2/Client_Growrk/_modules.txt |
+| [Auditing a client DB that drifted from its models (partially applied module migration)](workflows/client-schema-drift-audit.md) | A recurring 2.0 failure mode: **one client's database drifts from what the PHP models declare**, usually because a `_modules/<module>/` migration was applied to | dbchanges2/Client_Growrk/2026-05-28.sql, dbchanges2/Client_Growrk/2026-08-10c - GrowrkServiceRequestCustomFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10d - GrowrkServiceRequestTypeAndDispositionSeeds.sql, dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Growrk/2026-08-10 - GrowrkUnitInventoryFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10b - GrowrkUnitItemDescriptionAcl.sql, dbchanges2/Client_Growrk/_modules.txt |
 | [Local vs prod MySQL config parity — why “it passed locally” is not evidence](workflows/local-vs-prod-mysql-config-parity.md) | Several migration failures that look like "prod-only bugs" are actually **per-machine MySQL server-configuration differences**. |  |
 | [Repairing non-prod metadata drift (works in prod, broken in beta/dev-sandbox)](workflows/nonprod-metadata-drift-repair.md) | Almost all 2.0 platform behavior is **metadata** — `Core.Records`/`RecordFields`, `Core.RecordScripts`, `Core.ApiPayloadInterceptors`, and per-client `Acl*` row | dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql, dbchanges2/Core/2026-07-16a - TrackingNumberSignatureTypeRecordField.sql, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql, api2/Config/beta.ini |

package/knowledge/2.0/apps/dbchanges2/workflows/client-schema-drift-audit.md

@@ -6,9 +6,12 @@ project: Database Changes
 client: shared
 type: workflow
 status: active
-updated: 2026-08-10
-owners: ["bala"]
+updated: 2026-08-11
+owners: ["bala", "mhammontree"]
 files:
+  - dbchanges2/Client_Growrk/2026-05-28.sql
+  - dbchanges2/Client_Growrk/2026-08-10c - GrowrkServiceRequestCustomFieldsCatchUp.sql
+  - dbchanges2/Client_Growrk/2026-08-10d - GrowrkServiceRequestTypeAndDispositionSeeds.sql
   - dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql
   - dbchanges2/Client_Growrk/2026-08-10 - GrowrkUnitInventoryFieldsCatchUp.sql
   - dbchanges2/Client_Growrk/2026-08-10b - GrowrkUnitItemDescriptionAcl.sql
@@ -38,6 +41,36 @@ Written from repairing `Client_Growrk.Units` (missing `c_lastModified`, 6 of 7 c
 metadata rows applied) — see
 [GroWrk Units custom fields](../../../../clients/growrk/features/units-netsuite-custom-fields.md).
 
+## First question: was the file PARTIALLY applied, or NEVER applied? (corrected 2026-08-11)
+
+The `Client_Growrk` incidents were originally diagnosed as a **partially applied** module migration.
+**That was wrong.** The real cause was **`Client_Growrk/2026-05-28.sql`, committed on `_main`
+(`af30e63`) but NEVER EXECUTED against production** — one skipped commit that explained **two**
+separate 500 incidents (`Units.c_lastModified` on 2026-08-10 and
+`ServiceRequests.c_externalReferenceId` on 2026-08-11).
+
+> **"Committed to `_main`" is not "applied to production."** Establish which of the two you are looking
+> at **before** writing a catch-up file, because the repair scope is completely different.
+
+**Cheapest discriminator — count the file's fixed UUID literals in the client DB:**
+
+- **zero present → the file never ran.** Then audit **every object the file touches**, not just the
+  column in the stack trace. In the GroWrk case that meant `ServiceRequests` `c_` columns 0 of 2,
+  `CustomRecordFields` recordId 35 0 of 2, `ServiceRequestTypes` 2 of 19, `UnitDispositions` 1 of 5,
+  and two **whole missing objects** from sibling files in the same commit (`Core.Records` 315 and
+  `Client_Growrk.UnitTypes`).
+- **some present → genuinely partial.** Repair statement by statement.
+
+**Rule out an executor date-window gap explicitly** by checking that files with **both earlier and
+later** dates in the same folder did apply (2026-06-17 and 2026-07-31 both had, straddling the skipped
+2026-05-28) — otherwise you will "fix" the wrong thing.
+
+**Check the sibling files in the same git commit.** A skipped commit usually drops **every** file it
+carried, across `Core/`, `Client/` and `Client_<Name>/` folders.
+
+**Fix production AND beta.** A hand-fix applied to production only leaves beta still drifted, so the
+catch-up migration is a **prerequisite for testing on beta** even though production already works.
+
 ## Why it 500s: `_Model` ignores the caller's `fields=`
 
 `_Model` builds its SELECT from **every declared property on the class and its traits**, not from
@@ -122,6 +155,18 @@ part, and it is what makes a missing column fatal. Standard, non-`c_` fields use
 
 ## Change history
 
+- 2026-08-11 — TRUE-80824: **corrected the premise.** The `Client_Growrk` drift was **not** a partially
+  applied module migration — `Client_Growrk/2026-05-28.sql` is committed on `_main` (`af30e63`) and was
+  **never executed** against production, which explains both the 2026-08-10 `Units` 500s and the
+  2026-08-11 `ServiceRequests.c_externalReferenceId` Fulfill & Ship 500s. Added the
+  **partial-vs-never-applied discriminator** (count the file's fixed UUID literals: zero present = never
+  ran, so audit every object the file touches, plus the sibling files in the same git commit), the
+  requirement to **rule out an executor date-window gap** by confirming earlier and later files applied,
+  and the note that a production-only hand-fix leaves **beta** drifted so the catch-up file is a
+  prerequisite for beta testing. Also recorded the API-diagnostics traps found on the way: `error.id`
+  `95-24` = `Logs.Issue.issueNumber`/`Logs.Event.eventNumber` (not Issue `id`), and
+  `Logs.Api.transactionId` stores a **timestamp**, so a request cannot be found by the envelope's
+  transactionId. (mhammontree)
 - 2026-08-10 — Created from the production `Client_Growrk.Units` incident: `_Trait_Netsuite_Unit`
   declared `c_lastModified` but the column had never been added, so **every** traversal reaching a
   Growrk Unit 500'd (`EO-1`, MySQL 1054) regardless of the requested `fields=`. Recorded the

package/knowledge/2.0/apps/toga2-supply/INDEX.md

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [TOGa Supply (toga2-supply) Architecture](architecture.md) | `toga2-supply` is the **React + Vite frontend** for TOGa Supply — warehouse fulfillment tooling (shipment selection, fulfill & ship against carrier APIs, NetSui | toga2-supply/src/api/toga.ts, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx |
-| [Fulfill & Ship](features/fulfill-and-ship.md) | Fulfill & Ship lets a warehouse user select sales-order line items, enter serials, pick a carrier/method, and in one action: create the Item Fulfillment records | _underscore/Model/Client/Measure.php, _underscore/Model/Client/TrackingNumber.php, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/getEditShipmentFormOptions.ts, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/validateFormOnSubmit.ts, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/checkDimensions.ts, toga2-supply/src/components/ui/Tables/BasicTable/BasicTable.tsx, toga2-supply/src/components/ui/Tables/types.ts, toga2-supply/src/components/ui/GoogleMapsLink.tsx, toga2-supply/src/pages/ShipmentItems/view/forms/ShipmentItemsTable.tsx, toga2-supply/src/pages/ShipmentItems/api/ShipmentItemsApi.ts, toga2-supply/src/pages/ShipmentItems/types.ts, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/RETURNLABELFIELDS.json, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/components/ui/BaseInput/UnitSelect.tsx, toga2-supply/src/pages/EditShipment/view/modals/SerialNumbersModal.tsx, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/pages/EditShipment/view/components/SelectedShipmentItemsTable.tsx, toga2-supply/src/pages/EditShipment/view/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/DUMMYUPDATESHIPMENTFIELDS.json, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/tailwind.config.cjs, toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx, toga2-supply/src/styles/index.scss, toga2-supply/src/components/ui/BaseInput/BaseInput.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/EditShipment/viewModel/signatureTypes.ts, toga2-supply/src/pages/EditShipment/view/modals/SelectReturnAddressModal.tsx, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/formatShipmentData.ts, toga2-supply/src/pages/EditShipment/types.ts, toga2-supply/src/pages/Shipments/view/ShipmentsPage.tsx, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, toga2-supply/src/pages/Shipments/types.ts, toga2-supply/src/pages/FulfilledShipments/view/FulfilledShipmentsPage.tsx, toga2-supply/src/components/ui/CardTable/CardTable.tsx, toga2-supply/src/components/ui/CardTable/types.ts, toga2-supply/src/assets/pen-line.svg, _underscore/Model/Client/ItemFulfillment.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php |
+| [Fulfill & Ship](features/fulfill-and-ship.md) | Fulfill & Ship lets a warehouse user select sales-order line items, enter serials, pick a carrier/method, and in one action: create the Item Fulfillment records | _underscore/Trait/Netsuite/SalesOrder.php, dbchanges2/Client_Growrk/2026-08-10e - GrowrkUpsServiceMethodCodes.sql, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, _underscore/Model/Client/Measure.php, _underscore/Model/Client/TrackingNumber.php, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/getEditShipmentFormOptions.ts, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/validateFormOnSubmit.ts, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/checkDimensions.ts, toga2-supply/src/components/ui/Tables/BasicTable/BasicTable.tsx, toga2-supply/src/components/ui/Tables/types.ts, toga2-supply/src/components/ui/GoogleMapsLink.tsx, toga2-supply/src/pages/ShipmentItems/view/forms/ShipmentItemsTable.tsx, toga2-supply/src/pages/ShipmentItems/api/ShipmentItemsApi.ts, toga2-supply/src/pages/ShipmentItems/types.ts, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/RETURNLABELFIELDS.json, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/components/ui/BaseInput/UnitSelect.tsx, toga2-supply/src/pages/EditShipment/view/modals/SerialNumbersModal.tsx, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/pages/EditShipment/view/components/SelectedShipmentItemsTable.tsx, toga2-supply/src/pages/EditShipment/view/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/DUMMYUPDATESHIPMENTFIELDS.json, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/tailwind.config.cjs, toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx, toga2-supply/src/styles/index.scss, toga2-supply/src/components/ui/BaseInput/BaseInput.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/EditShipment/viewModel/signatureTypes.ts, toga2-supply/src/pages/EditShipment/view/modals/SelectReturnAddressModal.tsx, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/formatShipmentData.ts, toga2-supply/src/pages/EditShipment/types.ts, toga2-supply/src/pages/Shipments/view/ShipmentsPage.tsx, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, toga2-supply/src/pages/Shipments/types.ts, toga2-supply/src/pages/FulfilledShipments/view/FulfilledShipmentsPage.tsx, toga2-supply/src/components/ui/CardTable/CardTable.tsx, toga2-supply/src/components/ui/CardTable/types.ts, toga2-supply/src/assets/pen-line.svg, _underscore/Model/Client/ItemFulfillment.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php |
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-supply` (React + Vite) builds and deploys on **AWS Amplify**. | toga2-supply/amplify.yml, toga2-supply/.gitattributes, toga2-supply/.github/workflows/sync-stage-environments.yml, toga2-supply/.env.qc-security |
 | [Onboarding a client to the supply2 frontend (host-scoping)](workflows/client-host-scoping.md) | How a new tenant becomes a "client" in the `toga2-supply` frontend. | toga2-supply/src/stores/useHostNameStore.ts, toga2-supply/src/utils/resolveClientHostName.ts, toga2-supply/src/hooks/useHostName.tsx, toga2-supply/src/hooks/usePageDetails.tsx, toga2-supply/src/hooks/usePageListDetails.tsx, toga2-supply/src/components/layout/SlideMenu/SlideMenu.tsx, toga2-supply/src/utils/handleClientAuthentication.ts, toga2-supply/src/App.tsx, toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts, toga2-supply/src/pages/Inventory/viewModel/FIELDS/INVENTORYPAGEFIELDS.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/pages/Orders/OrdersPage.tsx, 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/utils/convertConstructorColumnTitles.ts, toga2-supply/src/api/toga.ts, toga2-supply/package.json |
+| [Onboarding a client to TOGa Supply Fulfill & Ship](workflows/onboarding-a-client-to-fulfill-and-ship.md) | **Onboarding a client to Fulfill & Ship is CONFIGURATION, not development** — unless the client wants tracking pushed into their own system. | _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Trait/Netsuite/ItemFulfillment.php, dbchanges2/_modules/netsuite/ |

package/knowledge/2.0/apps/toga2-supply/features/fulfill-and-ship.md

@@ -6,9 +6,12 @@ project: TOGa Supply
 client: shared
 type: feature
 status: active
-updated: 2026-08-03
+updated: 2026-08-11
 owners: [mhammontree]
 files:
+  - _underscore/Trait/Netsuite/SalesOrder.php
+  - dbchanges2/Client_Growrk/2026-08-10e - GrowrkUpsServiceMethodCodes.sql
+  - toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx
   - _underscore/Model/Client/Measure.php
   - _underscore/Model/Client/TrackingNumber.php
   - toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/getEditShipmentFormOptions.ts
@@ -55,6 +58,8 @@ related:
   - ../architecture.md
   - ../../_underscore/features/carrier-shipping-labels.md
   - ../../_underscore/features/recursive-item-fulfillments.md
+  - ../../_underscore/features/netsuite-salesorder-address-phone-sync.md
+  - ../workflows/onboarding-a-client-to-fulfill-and-ship.md
 ---
 
 ## Summary
@@ -184,12 +189,38 @@ bare string** — see the gotcha below before wiring a new select field.
   `renderEditShipmentFormInput` rendering it via `BaseDisabledInput` on an `isReadOnly` flag. **Not
   persisted to `IF.locationId`** for now — persisting would be a separate backend "set from SO"
   change plus a NetSuite-mapping check.
-- **Reference 1 / Reference 2 are WIRED (2026-07-31, TRUE-80494) — user-entered, NOT persisted.**
-  Definitions confirmed: **Reference 1 = NetSuite Sales Order #, Reference 2 = NetSuite Purchase
+- **Reference 1 / Reference 2 / Phone # are now PREFILLED from NetSuite (2026-08-11, TRUE-80824) —
+  still user-overridable, still NOT persisted.** ⚠ **This supersedes the earlier SME (Skyler) note
+  that they are "user-entered, NOT prefilled from NetSuite"** — that half is no longer true; the
+  "not persisted" half still is. Sources, confirmed against production data:
+  **Reference 1 = `SalesOrders.number`**; **Reference 2 = NetSuite's `otherRefNum`**, which the SO
+  sync stores as a **`PurchaseOrder` reached through the `PurchaseOrders_SalesOrders` bridge** —
+  **NOT `SalesOrders.customerPurchaseOrder`** (only ~59% populated and NULL on the order tested,
+  while the bridge covers **12,643 of 12,658** orders); **Phone # = the NetSuite shipping address's
+  `addrPhone`** (see the
+  [NetSuite SO address/phone sync doc](../../_underscore/features/netsuite-salesorder-address-phone-sync.md)).
+  Frontend rules learned wiring the prefill:
+  - `phoneNumber` was set **only** by the edit-mode rehydrate and was **missing from
+    `defaultValues`** (create mode always opened blank even when the address had a phone) **and
+    missing from the `ShipmentData` type**, despite being assigned on the edit path and read by
+    `validateFormOnSubmit`.
+  - **`reset()` in edit mode replaces the WHOLE form state** and omitted `reference1`/`reference2`,
+    which blanked the prefill on every edit-mode load. Anything prefilled must be re-supplied in
+    every `reset()` call.
+  - **Carrier references are truncated to 35 chars in THREE places** — at defaults, at the edit-mode
+    `reset()`, and again immediately before `fulfillShipment` — because a **programmatic prefill
+    bypasses the field config's `characterLimit`** (a 36-char GroWrk PO was observed).
+  - The rehydrate effect's dep array was deliberately **left as `[editShipment]`**: adding the
+    reference values would re-run `reset()` and **discard a user's in-progress edits**.
+  - **No ACL migration was needed for the reads** — grants already exist for `sales-orders.number`
+    (`RecordFields` 49), `purchase-orders.number` (87) and the bridge (1891/1892) on roles 1 and 3.
+  - **A blank phone on an OLD order is not a failed deploy** (decision, Mark: **no backfill**) — the
+    phone only appears on sales orders that **re-sync from NetSuite after deploy**.
+
+  Definitions (unchanged): **Reference 1 = NetSuite Sales Order #, Reference 2 = NetSuite Purchase
   Order #** (the field-config placeholders were authoritative over the initial verbal description,
-  and testing confirmed it — `281144` = `SalesOrders.number` — entered into Reference 1). Per SME
-  (Skyler) the values are **user-entered, NOT prefilled from NetSuite, and NOT persisted**; their
-  **sole purpose is to reach the carrier and print on the label**. Implemented as **transient
+  and testing confirmed it — `281144` = `SalesOrders.number` — entered into Reference 1). Their
+  **purpose is to reach the carrier and print on the label**. Implemented as **transient
   query-string params** on the existing carrier RecordScript calls (`fulfillShipment` in
   `UpdateShipmentApi.ts` → `upsShipmentApi`/`fedexShipmentApi`) — **no defaultValues, no save
   payload, no DB columns, zero `dbchanges2` work**. Form enforces `characterLimit: 35` (carrier
@@ -532,9 +563,37 @@ the call 403s and returns no label.
 - **UPS address limits**: `AddressLine` max 35 chars/line; code currently sends
   `line1 + ' ' + line2` as one line — should send a trimmed array (FedEx path already
   does).
-- **Service codes are carrier-scoped**: UPS numeric (`03`=Ground, `01`=Next Day Air),
-  FedEx strings (`FEDEX_GROUND`), in `ShippingMethods.code`. Empty code → UPS 120500;
-  there is now a fast-fail guard.
+- **⚠⚠ `ShippingMethods.code` is EMPTY in production for most clients — and the UI gives the user no
+  signal.** Service codes are carrier-scoped: UPS numeric (`03`=Ground, `01`=Next Day Air), FedEx
+  strings (`FEDEX_GROUND`). The chain is `ShippingMethods.code` → `shippingMethodCode`
+  (`Model/Client/ItemFulfillment.php`) → `$shipmentRequest->service` → UPS `'Service' => ['Code']`
+  (`Component/Library/Carriers/Ups/Ups.php`); an empty string → **UPS 120500 "missing or invalid
+  service code"**. **The dropdown renders `name`, not `code`, so the form looks completely normal** —
+  a warehouse user cannot tell a method is unusable. Production state found 2026-08-11: **GroWrk
+  ids 3 and 4 were NULL and were fixed** (`Client_Growrk/2026-08-10e - GrowrkUpsServiceMethodCodes.sql`);
+  **Elite 0 of 6** methods coded, **Quad 0 of 12**, **Rate 0 of 4**, **Compass 1 of 23** — and that one
+  is `'GND'`, **not a valid UPS REST code**. **Verify `ShippingMethods.code` per client before
+  believing a shipping failure is a code bug.**
+- **⚠ GroWrk `ShippingMethods` ids 11/12 ("Overnight Standard" / "Overnight Priority") are still
+  NULL — FedEx product names sitting on UPS rows**, duplicating Next Day Air. Left NULL pending a
+  data-owner decision (assign real codes or delete the rows); until then, selecting either fails.
+- **⚠ Duplicate `SalesOrders` rows per NetSuite SO id (historic, `Client_Growrk`) break fulfillment
+  and make the form's address arbitrary.** Production 2026-08-11: **12,658 rows for 7,776 distinct
+  `c_netsuiteInternalSalesOrderId`**, **2,787 ids duplicated (36%)**, worst case **139 rows sharing
+  one id and one `number`**. **Historic, not ongoing** — since 2026-08-01 it is 111 rows / 111
+  distinct ids. Two consequences: (a) `POST /item-fulfillments` resolves `salesOrder` by
+  `c_netsuiteInternalSalesOrderId` and needs **exactly one** match, so a duplicated order fails
+  **EV-12**; (b) `getAddress()` returns **all** matches and `EditShipmentPage` takes
+  **`salesOrders[0]`**, so which ship-to address and PO the form shows is **arbitrary** (beta SO
+  7221433 has 2 rows with **different `shipToAddressId`** and different `PurchaseOrder` rows).
+  **Needs its own ticket:** data dedupe **plus** a decision on whether the code should fail loudly
+  instead of silently taking `[0]`.
+- **⚠ The reprint scripted route is NOT registered in production `Core.RecordScripts` — reprint is
+  broken for EVERY client.** This doc (and the carrier doc) describe reprint as
+  `GET /v2/tracking-numbers/reprint` → `_Model_Client_TrackingNumber::reprintLabelsApi`, but
+  production `Core.RecordScripts` has **no `tracking-numbers` rows at all**; the only label-related
+  script is `generateReturnLabel` (id **26**, `item-fulfillments`). Discovered 2026-08-11, **not
+  fixed — needs its own ticket** (register the RecordScript + its `AclRecordScripts` grants).
 - **Serialized inventory needs a location**: a SO with no Warehouse Location makes
   NetSuite reject the serial issue ("Invalid issueinventorynumber reference key").
   Recommended hardening: always scope `getInventoryNumberFromSerialNumber` by location.
@@ -761,6 +820,22 @@ not the base `_Model_Client_ItemFulfillment`. Tested with GroWrk; UPS support wa
 for Compass and is not yet in prod.
 
 ## Change history
+- 2026-08-11 — TRUE-80824: **Reference 1 / Reference 2 / Phone # are now PREFILLED from NetSuite**
+  (still user-overridable, still not persisted) — **correcting the earlier SME note that they are
+  never prefilled**. Confirmed sources against production: Ref1 = `SalesOrders.number`; Ref2 =
+  NetSuite `otherRefNum`, stored as a `PurchaseOrder` via the `PurchaseOrders_SalesOrders` bridge
+  (**not** `customerPurchaseOrder`, ~59% populated vs the bridge's 12,643/12,658); Phone = the NetSuite
+  shipping address's `addrPhone`. Frontend fixes: `phoneNumber` missing from `defaultValues` **and**
+  from the `ShipmentData` type; edit-mode `reset()` omitted `reference1`/`reference2` and blanked the
+  prefill; references truncated to 35 chars in three places because a programmatic prefill bypasses
+  the config `characterLimit`; rehydrate dep array deliberately kept `[editShipment]` so a user's
+  in-progress edits aren't discarded. Also recorded four production data findings: **`ShippingMethods.code`
+  is empty for most clients** (GroWrk ids 3/4 fixed; Elite 0/6, Quad 0/12, Rate 0/4, Compass 1/23 with
+  an invalid `'GND'`) and the dropdown shows `name` so the UI looks fine; GroWrk ids 11/12 are FedEx
+  names on UPS rows, left NULL pending a data-owner decision; **duplicate `SalesOrders` rows** per
+  NetSuite SO id (12,658/7,776; 36% duplicated; historic) causing EV-12 and an arbitrary
+  `salesOrders[0]` address; and the **reprint RecordScript is not registered in production**, so
+  reprint is broken for every client. The last two need their own tickets. (mhammontree)
 - 2026-08-03 — TRUE-80494 (hotfix + feature follow-up to TRUE-79191): **ended a TOTAL production
   Fulfill & Ship submit outage** (all clients, since the 2026-07-29 deploy) — the display-only
   "Address" section header (`valueKey: ""`, `isRequired: true`) always produced a validation error

package/knowledge/2.0/apps/toga2-supply/workflows/onboarding-a-client-to-fulfill-and-ship.md

@@ -0,0 +1,72 @@
+---
+title: Onboarding a client to TOGa Supply Fulfill & Ship
+framework: "2.0"
+repo: toga2-supply
+project: TOGa Supply
+client: shared
+type: workflow
+status: active
+updated: 2026-08-11
+owners: ["mhammontree"]
+files:
+  - _underscore/Trait/Netsuite/SalesOrder.php
+  - _underscore/Trait/Netsuite/ItemFulfillment.php
+  - dbchanges2/_modules/netsuite/
+related:
+  - ../features/fulfill-and-ship.md
+  - ../../_underscore/features/carrier-shipping-labels.md
+  - ../../_underscore/features/acl-permission-chain.md
+  - ../../dbchanges2/workflows/client-onboarding.md
+  - ../../../1.0/apps/worker/workflows/onboarding-client-to-netsuite-togasupply-sync.md
+---
+
+## Summary
+
+**Onboarding a client to Fulfill & Ship is CONFIGURATION, not development** — unless the client wants
+tracking pushed into their own system. Derived from a **GroWrk-vs-Elite production diff** (2026-08-11);
+the platform-wide pieces were already shared by both clients, and only two things are genuinely
+per-client.
+
+## Already shared — nothing to do
+
+These were **identical** between the working client (GroWrk) and a candidate (Elite):
+
+- **Client models composing the NetSuite traits** — 22 clients have **both**
+  `_Trait_Netsuite_SalesOrder` and `_Trait_Netsuite_ItemFulfillment`.
+- **NetSuite sync `Parameters`** — 16 keys.
+- **`Measures`** — Inch / Pound seeded.
+- **`AclRecordScripts` grants** — GroWrk and Elite hold **identical `recordScriptId` sets**
+  (1-19, 22, 26, 27).
+
+## Required PER CLIENT
+
+1. **`ShippingCarrierAccountNumbers`** — Elite has **0**. The Carrier dropdown only lists carriers
+   that have **at least one account number**, so with none the user sees an **empty list** with no
+   error.
+2. **`ShippingMethods.code` per carrier** — UPS numeric (`03` Ground, `01` Next Day Air), FedEx
+   strings (`FEDEX_GROUND`). **Empty → UPS 120500**, and the dropdown renders `name` not `code`, so
+   the form looks normal. In production this is empty for most clients — see the fulfill-and-ship
+   doc's service-code gotcha.
+
+## Required on the NetSuite side
+
+The sales order needs a **warehouse `Location`**, or NetSuite rejects the serial with **"Invalid
+issueinventorynumber reference key"** — and the serials must be **on hand at that location**.
+
+## Optional and code-bearing
+
+A **per-client `postPost` webhook** via `ApiPayloadInterceptors` to push tracking into the client's own
+system. This is **GroWrk-only today** and is the one part that is development, not configuration. (It
+also means the client model gains custom `c_` fields — see
+[client schema-drift audit](../../dbchanges2/workflows/client-schema-drift-audit.md), because the
+interceptor is what makes a missing `c_` column fatal.)
+
+## Change history
+
+- 2026-08-11 — TRUE-80824: created from a GroWrk-vs-Elite production diff while investigating whether a
+  second client could use Fulfill & Ship. Conclusion: onboarding is configuration — the traits,
+  NetSuite sync Parameters (16 keys), Inch/Pound Measures and `AclRecordScripts` sets (1-19, 22, 26, 27)
+  are already identical across clients; only **`ShippingCarrierAccountNumbers`** (Elite has 0 → empty
+  Carrier dropdown) and **`ShippingMethods.code`** are per-client, plus a NetSuite warehouse Location
+  with serials on hand. A per-client `postPost` tracking webhook (`ApiPayloadInterceptors`, GroWrk-only)
+  is the only code-bearing option. (mhammontree)

package/knowledge/INDEX.md

@@ -18,11 +18,11 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 51 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 52 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 46 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)
-- **toga2-supply** (TOGa Supply) — 5 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
+- **toga2-supply** (TOGa Supply) — 6 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **toga2-view** (TOGa View Frontend) — 7 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
 - **toga2-hub** (TOGa Hub) — 2 doc(s) → [2.0/apps/toga2-hub/INDEX.md](2.0/apps/toga2-hub/INDEX.md)

package/knowledge/clients/growrk/INDEX.md

@@ -3,5 +3,5 @@
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
 | [Transfer Order Flow (NetSuite SalesOrder workaround → dedicated TransferOrders)](features/transfer-order-flow.md) | 2.0 | GroWrk moves inventory between their own locations (warehouses, distribution points). | _underscore/Model/Client/TransferOrder.php, _underscore/Model/Client/TransferOrderItem.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemReceipt.php, _underscore/Model/Client/ItemReceiptItem.php, _underscore/Trait/Netsuite/TransferOrder.php, dbchanges2/Client_Growrk/, dbchanges2/Client/ |
-| [GroWrk Units — NetSuite-module custom fields (the c_lastModified 500 incident)](features/units-netsuite-custom-fields.md) | 2.0 | GroWrk is on the dbchanges2 **`netsuite`** module (`dbchanges2/Client_Growrk/_modules.txt`), so its Units carry the module's seven `c_` custom fields. | _underscore/Trait/Netsuite/Unit.php, _underscore/Model/Growrk/Unit.php, dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Growrk/2026-08-10 - GrowrkUnitInventoryFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10b - GrowrkUnitItemDescriptionAcl.sql, dbchanges2/Client_Growrk/_modules.txt |
+| [GroWrk NetSuite-module custom fields — the never-executed 2026-05-28 commit (Units + ServiceRequests 500s)](features/units-netsuite-custom-fields.md) | 2.0 | GroWrk is on the dbchanges2 **`netsuite`** module (`dbchanges2/Client_Growrk/_modules.txt`), so its Units carry the module's seven `c_` custom fields. | _underscore/Trait/Netsuite/Unit.php, _underscore/Model/Growrk/Unit.php, _underscore/Model/Growrk/ItemFulfillment.php, dbchanges2/Client_Growrk/2026-05-28.sql, dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Growrk/2026-08-10 - GrowrkUnitInventoryFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10b - GrowrkUnitItemDescriptionAcl.sql, dbchanges2/Client_Growrk/2026-08-10c - GrowrkServiceRequestCustomFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10d - GrowrkServiceRequestTypeAndDispositionSeeds.sql, dbchanges2/Client_Growrk/_modules.txt |
 | [GroWrk](profile.md) | 2.0 | GroWrk is a 2.0 client using TOGA for inventory and order management. |  |

package/knowledge/clients/growrk/features/units-netsuite-custom-fields.md

@@ -1,19 +1,23 @@
 ---
-title: "GroWrk Units — NetSuite-module custom fields (the c_lastModified 500 incident)"
+title: "GroWrk NetSuite-module custom fields — the never-executed 2026-05-28 commit (Units + ServiceRequests 500s)"
 framework: "2.0"
 repo: _underscore
 project: _Underscore
 client: growrk
 type: client-feature
 status: active
-updated: 2026-08-10
+updated: 2026-08-11
 owners: ["bala", "mhammontree", "rgirish"]
 files:
   - _underscore/Trait/Netsuite/Unit.php
   - _underscore/Model/Growrk/Unit.php
+  - _underscore/Model/Growrk/ItemFulfillment.php
+  - dbchanges2/Client_Growrk/2026-05-28.sql
   - dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql
   - dbchanges2/Client_Growrk/2026-08-10 - GrowrkUnitInventoryFieldsCatchUp.sql
   - dbchanges2/Client_Growrk/2026-08-10b - GrowrkUnitItemDescriptionAcl.sql
+  - dbchanges2/Client_Growrk/2026-08-10c - GrowrkServiceRequestCustomFieldsCatchUp.sql
+  - dbchanges2/Client_Growrk/2026-08-10d - GrowrkServiceRequestTypeAndDispositionSeeds.sql
   - dbchanges2/Client_Growrk/_modules.txt
 related:
   - ../profile.md
@@ -32,12 +36,69 @@ Units carry the module's seven `c_` custom fields. `_Model_Growrk_Unit` is *only
 declared by the trait**, and each must exist as a physical column in `Client_Growrk.Units`, as a
 `CustomRecordFields` row (recordId **31** = Units), and as an `AclCustomFieldPermissions` grant.
 
-On **2026-08-10** production GroWrk 500'd on `GET /v2/item-fulfillments` because one of those
-columns — `c_lastModified` — had never been created: the module migration
-`_modules/netsuite/2026-07-10a - UnitInventoryFields.sql` had applied to `Client_Growrk` only
-**partially**. Two catch-up migrations fixed it in production; the general playbook lives in
+On **2026-08-10** production GroWrk 500'd on `GET /v2/item-fulfillments` (missing `Units.c_lastModified`)
+and on **2026-08-11** it 500'd again on POST/PUT `/v2/item-fulfillments` (missing
+`ServiceRequests.c_externalReferenceId`). **Both incidents have ONE root cause** — see the corrected
+root cause below. Catch-up migrations fixed each in production; the general playbook lives in
 [client schema-drift audit](../../../2.0/apps/dbchanges2/workflows/client-schema-drift-audit.md).
 
+## ⚠ CORRECTED ROOT CAUSE (2026-08-11) — one commit was never executed, nothing was "partially applied"
+
+This doc originally attributed the 2026-08-10 Units 500 to a **partially applied**
+`_modules/netsuite/2026-07-10a - UnitInventoryFields.sql`. **That was wrong.** The real cause of both
+incidents is that **`dbchanges2/Client_Growrk/2026-05-28.sql` is committed on `_main`
+(`af30e63`, rgirish97, 2026-06-02) but was NEVER EXECUTED against production.**
+
+- **Lines 26-31 of that file add the same five `Units` `c_` columns** that looked like a partial
+  module run. One skipped commit explains both incidents; there is no evidence of any file applying
+  half-way.
+- All three files in that commit are absent from production — including
+  `Core/` and `Client/` **"2026-06-01 - UnitTypes.sql"**: `Core.Records` 315 and
+  `Client_Growrk.UnitTypes` **do not exist** in production.
+- **It is NOT an executor date-window gap.** `2026-06-17` and `2026-07-31` files both applied,
+  straddling the skipped date.
+- **Measured drift from the unexecuted file:** `ServiceRequests` `c_` columns **0 of 2**;
+  `CustomRecordFields` recordId 35 **0 of 2**; `ServiceRequestTypes` **2 of 19**;
+  `UnitDispositions` **1 of 5**; and **none of the file's 7 fixed UUIDs** present anywhere.
+
+> **Durable lesson: "committed to `_main`" is not "applied to production."** Before theorising about a
+> partial run, check whether the whole file ran at all — the cheapest proof is whether **any** of its
+> fixed UUIDs exist in the client DB. Zero present = never executed; some present = truly partial.
+
+## The 2026-08-11 production outage — Fulfill & Ship EO-1 / HTTP 500
+
+**Symptom.** GroWrk Fulfill & Ship returned **EO-1 / HTTP 500** on **POST and PUT
+`/v2/item-fulfillments`** — both the *Save* and the *Fulfill & Ship* buttons.
+
+**Mechanism.** `ServiceRequests` lacked `c_externalReferenceId`, so the raw query in
+`_Model_Growrk_ItemFulfillment::sendGrowrkTrackingInfo()` (called from `postPost`) raised
+**MySQL 1054**.
+
+**Why it surfaced on that date, not in May.** Two things had to line up:
+1. the `postPost`/`postPut` **`ApiPayloadInterceptors`** (recordId **28**, both `isActive = 1`) landed
+   via `Client_Growrk/2026-07-31 - GrowrkItemFulfillmentTrackingWebhookInterceptors.sql`; and
+2. the **2026-08-05 NetSuite onboarding** switched GroWrk onto the `_Model_Growrk_*` classes, which
+   declare the `c_` fields.
+
+**Remediation (production):** `Client_Growrk/2026-08-10c - GrowrkServiceRequestCustomFieldsCatchUp.sql`
+(the 2 `ServiceRequests` `c_` columns + their recordId-35 `CustomRecordFields` rows and grants) and
+`2026-08-10d - GrowrkServiceRequestTypeAndDispositionSeeds.sql` (the missing `ServiceRequestTypes` /
+`UnitDispositions` seeds), both reusing the unexecuted file's fixed UUIDs.
+
+**No orphaned data resulted.** The exception rolls the insert back — `ItemFulfillments` `MAX(id)`
+stayed at **7645** across ~36 attempts; only auto-increment was burned.
+
+### Diagnostic recipes proven on this incident
+
+- **The API error id format `95-24` is `Logs.Issue.issueNumber` 95 / `Logs.Event.eventNumber` 24**
+  (that Issue's `id` is **166**) — **not** Issue id 95. Looking up id 95 finds an unrelated issue.
+- **`Logs.Api.transactionId` stores a TIMESTAMP, not the API transactionId.** You **cannot** find a
+  request by the `transactionId` in the JSON envelope — pivot on `error.id` instead.
+- **6 near-identical hits in ~12s sharing one transactionId is apiproxy's cross-region 5xx retry**,
+  not 6 user actions.
+- **Beta was still drifted** after the production hand-fix, because that fix went to production only —
+  so `2026-08-10c` is a prerequisite for testing the flow on beta.
+
 ## The seven fields (all from `_Trait_Netsuite_Unit`)
 
 `c_netsuiteInternalInventoryAssignmentId` (integer), `c_itemDescription`, `c_lastModified`,
@@ -62,9 +123,11 @@ first-seen timestamp of 18:03:22 exactly. Before onboarding, Units resolved thro
 `_Model_Client_Unit` (no `c_` fields at all), which is why the same request shape had **1,613
 successful 200s** right up to 2026-08-05 15:37:51.
 
-**Extent of the drift.** From `_modules/netsuite/2026-07-10a - UnitInventoryFields.sql`:
-**6 of its 7 Units columns** landed (`c_lastModified` did not) and **5 of its 6
-`CustomRecordFields` rows** never inserted.
+**Extent of the drift.** 6 of the 7 `Units` columns were present (`c_lastModified` was not) and 5 of
+the 6 `CustomRecordFields` rows were missing. This was originally read as a partial run of
+`_modules/netsuite/2026-07-10a - UnitInventoryFields.sql`; **the corrected explanation is the
+never-executed `Client_Growrk/2026-05-28.sql`** (see the corrected-root-cause section above), whose
+lines 26-31 add those same five `Units` columns.
 
 ## Remediation (applied to production and verified)
 
@@ -107,6 +170,21 @@ further 500s. The `ALTER` was an **instant** operation (MySQL 8.0.39, 5,415 `Uni
 
 ## Change history
 
+- 2026-08-11 — TRUE-80824: **Corrected this doc's root cause** and fixed a second production outage.
+  GroWrk Fulfill & Ship 500'd (`EO-1`) on POST **and** PUT `/v2/item-fulfillments` because
+  `ServiceRequests` lacked `c_externalReferenceId`, which
+  `_Model_Growrk_ItemFulfillment::sendGrowrkTrackingInfo()` (via `postPost`) selects — MySQL 1054.
+  The true cause of **both** this and the 2026-08-10 Units incident is that
+  `dbchanges2/Client_Growrk/2026-05-28.sql` is **committed on `_main` (`af30e63`) but was never
+  executed against production**; its lines 26-31 add the very five `Units` columns previously
+  attributed to a partially applied `_modules/netsuite/2026-07-10a`. Verified drift (0 of 2
+  `ServiceRequests` `c_` columns, 0 of 2 recordId-35 `CustomRecordFields`, 2 of 19
+  `ServiceRequestTypes`, 1 of 5 `UnitDispositions`, none of the file's 7 fixed UUIDs) and ruled out an
+  executor date-window gap (2026-06-17 and 2026-07-31 both applied). Shipped `2026-08-10c`/`2026-08-10d`
+  catch-ups reusing the fixed UUIDs. Recorded the diagnostics: `error.id` `95-24` =
+  `Issue.issueNumber`/`Event.eventNumber` (Issue id 166), `Logs.Api.transactionId` holds a **timestamp**
+  so the envelope transactionId is not searchable, and the exception rolled every insert back
+  (`ItemFulfillments` MAX(id) 7645 unchanged across ~36 attempts). (mhammontree)
 - 2026-08-10 — **Fixed** the production GroWrk 500s on `GET /v2/item-fulfillments`: `Units` was
   missing the `c_lastModified` column declared by `_Trait_Netsuite_Unit`, so `_Model`'s
   SELECT-all-declared-fields behaviour raised MySQL 1054 on **every** load of a Growrk Unit

package/knowledge/clients/growrk/profile.md

@@ -46,3 +46,17 @@ module (`dbchanges2/Client_Growrk/_modules.txt`).
   **1054s (unknown column) on any Unit load, on any route**. This is not only a local-drift
   problem — it took production down for GroWrk on 2026-08-10; see
   [Units — NetSuite-module custom fields](features/units-netsuite-custom-fields.md).
+- **⚠ `dbchanges2/Client_Growrk/2026-05-28.sql` (committed `af30e63`) was NEVER EXECUTED against
+  production**, which caused **two** separate production outages (Units 2026-08-10, ServiceRequests /
+  Fulfill & Ship 2026-08-11). Catch-ups `2026-08-10c`/`2026-08-10d` shipped; treat any other GroWrk
+  "missing column/metadata" report as possibly the same commit. See
+  [that doc](features/units-netsuite-custom-fields.md).
+- **⚠ Historic duplicate `SalesOrders` rows:** 12,658 rows for 7,776 distinct
+  `c_netsuiteInternalSalesOrderId` (36% duplicated, worst case 139 rows on one id). Not ongoing since
+  2026-08-01, but it fails `POST /item-fulfillments` with **EV-12** and makes the Fulfill & Ship
+  ship-to address arbitrary (`salesOrders[0]`). Needs its own ticket — see the
+  [Fulfill & Ship gotchas](../../2.0/apps/toga2-supply/features/fulfill-and-ship.md).
+- **`ShippingMethods` ids 11/12 ("Overnight Standard"/"Overnight Priority") have NULL `code`** — FedEx
+  product names on UPS rows, duplicating Next Day Air. Selecting either fails at UPS (120500);
+  awaiting a data-owner decision. Ids 3/4 were coded by
+  `Client_Growrk/2026-08-10e - GrowrkUpsServiceMethodCodes.sql`.

package/knowledge/clients/nycdoe/features/servicenow-integration.md

@@ -6,7 +6,7 @@ project: Worker
 client: nycdoe
 type: client-feature
 status: active
-updated: 2026-08-06
+updated: 2026-08-11
 owners: [mhammontree, sking]
 files:
   - worker/crons/sync/nycdoe/import_asn.php
@@ -207,6 +207,77 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
 
 ## Gotchas / known issues
 
+- **⚠ OPEN BUG / NAMED PATTERN — "Lenovo Off-Layout ASN File" (silent column shift + unit
+  collapse).** Investigated 2026-08-11 (read-only; **no code fix exists**). Lenovo sends
+  NYCDOE ASNs in **two different column layouts**, and `library/app/asnprocessor/lenovo.php`
+  picks its column mapping by **column COUNT with no header-name validation** (`:110`,
+  `if ($colCount >= 30`), so the off-layout file is parsed with the wrong mapping and
+  silently mis-read.
+  - **The two layouts.** The normal daily feed `DOE-Lenovo-ASN-MM-DD-YYYY.CSV` (~2 MB) has
+    **30** columns and matches the code's mapping. A second file,
+    `DOE-Open-Lenovo-MM-DD-YYYY.csv` (**lowercase** `.csv`, ~45 KB), has **31** columns in a
+    **different order**: `Contact Email` moves from column 29 to column **6**, and a trailing
+    `Full Shipment` column is appended. Everything from `Street Address` onward is therefore
+    read **one column too early**. The "extra comma" repair heuristic at `:119-127` does not
+    catch this (and is unchanged since March 2026 — commits `3442ddcf`, `6956dfbf`,
+    `864cf073`, so this is not a regression).
+  - **The four wrong values** (`lenovo.php:129-156`): `serialNumber` ← `$cols[22]` lands on
+    **System Quantity**, a constant `"1"` on every row (the real serial ends up in
+    `assetTag`); `orderQuantity` ← `$cols[21]` lands on a blank `Quantity Ordered`;
+    `partNumber` ← `$cols[17]` lands on the long **Product Description** instead of the OEM
+    SKU.
+  - **Diagnostic fingerprint.** `AdvanceShippingNoticeItems.partNumber` holds a long product
+    description rather than a SKU, and the ASN header carries shifted junk — `productClass` =
+    a tracking number, `workPhone` = a person's name, `shippingCarrier` = a date,
+    `dateShipped` = `1969-12-31` (unparseable date). Blast-radius query on `legacy`:
+    `SELECT id, advanceShippingNoticeItemId, serialNumber, assetTag FROM
+    Core.AdvanceShippingNoticeUnits WHERE serialNumber = '1'`.
+  - **Why units vanish silently.** Stage 1's dedupe key is
+    `vendorId|purchaseOrder|DOE-partNumber|serialNumber` and
+    `legacy_import_asn.php:64-68` does `$notices[$dedupeKey] = $asnLine` — **last occurrence
+    wins**. With `serialNumber` a constant `"1"`, every line of a given part collapses to one
+    key, losing N−1 units. Confirmed: `DOE-Open-Lenovo-08-07-2026.csv` (87 data lines for PO
+    `S202648137`) produced exactly **3** `Core.AdvanceShippingNoticeQueue` rows
+    (`476108-476110`, one per part), all `status='completed'`, `retryCount=0`, **no error and
+    no alert email** — so the max-retry alert never fires. Net effect on ASN `26720`: item
+    `54671` (monitor, `qtyOrder` 31) had **zero** `AdvanceShippingNoticeUnits` rows.
+  - **Systemic, not a one-off.** A production query found **13 pre-existing** Units rows
+    across *other* ASNs with `serialNumber = '1'` and the real serial in `assetTag` — this has
+    been corrupting DOE data for months.
+  - **Secondary amplifier:** `Core.AdvanceShippingNoticeItems.partNumber` is `varchar(64)` and
+    `sql_mode` is **non-strict** on the legacy cluster, so a description-as-partNumber is
+    **silently truncated** at 64 chars. That breaks `legacy_process_asn_queue.php`'s
+    item/unit lookup keys (built from the truncated DB value, compared against the full
+    in-memory string), and two long descriptions sharing their first 64 characters collapse
+    into the same item.
+  - **Remediation is MANUAL data repair — there is no automated recovery.** Correct
+    `Core.AdvanceShippingNoticeItems.partNumber` on the affected items to the real NetSuite
+    OEM SKU (replacing the description the malformed file supplied); the pipeline then
+    proceeds normally. Done this way for ASN `26720` on 2026-08-11.
+  - **Recommended future code fixes (proposed, NOT approved, NOT implemented):** map columns
+    by **header name** and hard-reject an unknown layout with a loud alert; stop building the
+    dedupe key from a field that can be a constant; widen
+    `AdvanceShippingNoticeItems.partNumber`.
+  - **UNRESOLVED.** On ASN `26720`, items `54672`/`54673` carried 31 and 25 units with
+    **correct** serials in `serialNumber` and `assetTag` NULL — which the three collapsed
+    queue rows cannot account for. The run that created those units was **not identified**.
+    Still open; do not assume it is explained.
+  - **Ruled out:** the recent **Quad** ASN import work is unrelated — Quad lives under
+    `worker/crons/toga2/**` against the toga2 `AdvanceShippingNoticeItemUnits` schema, while
+    the DOE path is `Core.AdvanceShippingNoticeUnits` via `asnprocessor/lenovo.php`.
+
+- **The "Outstanding Sales Orders - PO Reconciliation Required" email is FLEET-WIDE, not a
+  per-ASN alert** (`2_send_serials_to_netsuite.php:270-357`). It runs at the end of every
+  5-minute run and re-queries **all** `AdvanceShippingNoticeItems` with
+  `netSuiteInternalSalesOrderId` set but `netSuiteInternalPurchaseOrderId IS NULL`, throttled
+  to one email per 60 minutes via a sentinel `AdvanceShippingNoticeQueue` row with
+  `dedupeKey = 'system|po_reconciliation_alert'`. Receiving it means *at least one* SO is
+  unreconciled — it does **not** identify which ASN, so do not attribute it to the ASN you
+  happen to be looking at. A benign cause is simply that NetSuite has not created the PO from
+  the SO yet (`:76-82` logs "No POs found for NetSuite SO Internal ID <id>"). The subject's
+  count is also **inflated**: its `SELECT DISTINCT` includes `customerPurchaseOrder`, so it
+  counts SO+customerPO pairs rather than distinct SOs.
+
 - **⚠ NAMED PATTERN — "Pre-ASN Manual Receipt Mismatch"** (the umbrella condition covering
   this doc's two SO/PO-stamp gotchas below plus a third confirmed instance). Search this
   title, or its informal name **"Shipment Received Notice"** (Mark's nickname — some vendors,
@@ -447,6 +518,7 @@ use the toga DB MCP + `Logs.API` instead of running prod code locally.
    of the consumer query; `php -l` every touched file.
 
 ## Change history
+- 2026-08-11 — Investigated (read-only, **no code change**) ASN `26720` / PO `S202648137` never completing: root-caused the **"Lenovo Off-Layout ASN File"** bug — `asnprocessor/lenovo.php` maps columns by COUNT with no header validation, so the 31-column `DOE-Open-Lenovo-*.csv` shifts every field +1, making `serialNumber` the constant `"1"`, which collapses 87 source lines into 3 `completed` queue rows and loses units with no error/alert. Documented the diagnostic fingerprint, the 13-row systemic blast radius, the `varchar(64)` partNumber truncation amplifier, and the **manual** partNumber data repair as the only remediation. Also documented that the "Outstanding Sales Orders - PO Reconciliation Required" email is fleet-wide (and its count inflated), ruled out the Quad ASN work, and left the ASN `26720` items `54672`/`54673` correct-serial units as UNRESOLVED. (mhammontree)
 - 2026-08-06 — Named and cross-referenced the umbrella failure pattern **"Pre-ASN Manual
   Receipt Mismatch"** (aka "Shipment Received Notice") tying together the existing
   manually-edited-SO and cross-wired-stamp gotchas under one searchable title, and logged a

package/package.json

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