toga-ai 1.0.722 → 1.0.724

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-31
+updated: 2026-09-01
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -22,6 +22,7 @@ files:
   - test/@srija/Elite Testing/Service Requests/test_diagnose_togasupply_elite.php
 related:
   - ../architecture.md
+  - ../../../2.0/apps/_underscore/features/shipping-carriers-and-accounts.md
   - forecast2-netsuite-reconciliation.md
   - ../workflows/onboarding-client-to-netsuite-togasupply-sync.md
   - ../../library/features/toga2-api-client-and-bridge.md
@@ -336,6 +337,27 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
 
 ## Gotchas / known issues
 
+- **⚠ A lookup seeded as a BY-PRODUCT of another list will miss records — this created runaway
+  duplicate `ShippingCarriers` rows (fixed 2026-09-01, TRUE-81576).**
+  `$lookupShippingCarrierByClientUuidAndShippingCarrierNameUpper` was built only inside the
+  `/shipping-methods` loop, harvesting each method's parent carrier, so **a carrier with ZERO
+  shipping methods never entered the lookup**. The invoice sync's `!isset($lookup[$name])` check in
+  `library/app/api/toga2.php` (~L3194, fed by `App_Misc::getCarrierFromTrackingNumber`) then created
+  it **again every run** — and the new row also had no methods, so it stayed invisible. Unbounded
+  growth, one row per 5-minute sync. **The tell:** only **USPS and DHL** duplicated (17x / 6x on
+  GroWrk) — the two carriers with zero methods; FedEx (7 methods) and UPS (4) had exactly one row
+  each. Now seeded directly from a paged `GET /shipping-carriers`
+  (`MAX_RECORDS_PER_PAGE_TO_FETCH_FROM_TOGA_API` = 1000), blank names skipped. Full write-up:
+  [Shipping Carriers & Carrier Account Numbers](../../../2.0/apps/_underscore/features/shipping-carriers-and-accounts.md).
+  Same lesson as the manufacturer/catalog bug below: **initialise and seed a lookup from its own
+  source, not from a neighbouring loop.**
+- **⚠ A blank-named carrier matched EVERYTHING** — the matcher in `library/app/api/toga2.php` uses
+  `stripos($name, $carrierName) === 0`, and under PHP 8 an **empty needle returns `int(0)`**. The
+  placeholder became a catch-all and, having no account numbers, was invisible in the UI. Blank
+  names are now skipped **and** the creation branch reuses the existing blank placeholder instead of
+  POSTing a new `name => ''` carrier each run. **Those two changes must ship together** — skipping
+  blank names alone would make the placeholder permanently unmatchable and increase creation.
+
 - **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
@@ -821,6 +843,15 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
 
 ## Change history
 
+- 2026-09-01 — **TRUE-81576: stopped runaway duplicate `ShippingCarriers` creation (worker + library).**
+  `common_sync_togasupply.php` now seeds the carrier lookup from its own paged `GET /shipping-carriers`
+  loop instead of harvesting carriers out of the `/shipping-methods` loop — a carrier with zero
+  shipping methods was absent from the lookup, so the invoice sync recreated it every run (GroWrk had
+  17 USPS + 6 DHL duplicates; NYCHH 100 carriers, Compass 98). In `library/app/api/toga2.php` the
+  carrier matcher now **skips blank names** (an empty `stripos` needle returns `int(0)` and matched
+  every ship method) and the creation branch **reuses the existing blank placeholder** rather than
+  POSTing another empty-named carrier. Committed on branch `TRUE-81576`, PRs open. (mhammontree)
+
 - 2026-08-31 — **Item-receipt partial-receipt NULL-quantity fix (shared, `library`).**
   `syncItemReceiptFromNetsuite` now **skips line items whose `quantity` is null** (unreceived PO lines on a
   partial receipt) in both passes over `$nsItemReceipt->itemList->item` (payload-build ~L3376 + unit/serial

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 |
-| [FIELD_SQL calculated fields — the underscore-prefix + same-name-method contract](features/calculated-sql-fields.md) | A `FIELD_SQL` (calculated) field on a `_Model` is bound by a **two-part contract that `_Model` enforces by throwing at model-construction time**, not by convent | _underscore/Model.php, _underscore/Model/Client/SalesOrder.php, _underscore/Model/Client/ServiceRequest.php, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/Canada/SalesOrder.php, api2/Component/Api/V2/V2.php, _underscore/Model/Quad/Item.php, _underscore/Model/Quad/VendorItem.php, dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql, dbchanges2/Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql |
+| [FIELD_SQL calculated fields — the underscore-prefix + same-name-method contract](features/calculated-sql-fields.md) | A `FIELD_SQL` (calculated) field on a `_Model` is bound by a **two-part contract that `_Model` enforces by throwing at model-construction time**, not by convent | _underscore/Model.php, _underscore/Model/Client/PurchaseOrder.php, _underscore/Model/Client/SalesOrder.php, _underscore/Model/Client/ServiceRequest.php, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/Canada/SalesOrder.php, api2/Component/Api/V2/V2.php, _underscore/Model/Quad/Item.php, _underscore/Model/Quad/VendorItem.php, dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql, dbchanges2/Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql |
 | [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/Component/Library/Carriers/Usps/Usps.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 |
@@ -41,11 +41,12 @@
 | [Sales-order \"PO Number\" sourcing — one surface element, `_purchaseOrders`, tenant SQL underneath](features/sales-order-po-number-sourcing.md) | The sales-order modal's **PO Number** field is **not** tenant-split at the display layer. | _underscore/Model/Client/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/Canada/SalesOrder.php, dbchanges2/Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts, dbchanges2/Core/2026-08-25a - PoNumberDetailFieldPurchaseOrdersValueKey.sql, dbchanges2/Core/2026-07-23a - PoNumberDetailFieldValueKey.sql, dbchanges2/Client_Quad/2026-08-19a - PoDetailsButtonMostRecentPoSelection.sql |
 | [SO↔PO bridge tables are TWO tables in OPPOSITE directions (upstream vs downstream)](features/sales-order-purchase-order-bridge-direction.md) | There are **two** bridge tables linking sales orders and purchase orders, and they mean **opposite things**. | _underscore/Model/Client/PurchaseOrders/SalesOrder.php, _underscore/Model/Client/SalesOrders/PurchaseOrder.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/SalesOrder.php, _underscore/Trait/Netsuite/SalesOrder.php, library/app/api/toga2.php |
 | [Per-client sales-order status filter (Surface FILTER_SET → table meta `filterOptions`)](features/sales-order-status-filter-surface.md) | The status-filter dropdown on the sales-orders table is **per client**, driven by a Surface `FILTER_SET` rather than by the raw contents of the client's `SalesO | _underscore/Model/Client/TableView.php, _underscore/Model/Core/Surface.php, _underscore/Model/Client/SalesOrder.php, _underscore/Model/Quad/SalesOrder.php, _underscore/Model/Prudential/SalesOrder.php, toga-blox/src/components/Table/hooks/useFetchTablePageMeta.ts, toga-blox/src/api/types.ts, dbchanges2/Core/2026-08-24b - SalesOrderStatusFilterSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_CompassCanada/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Quad/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Nychh/2026-08-24b - SalesOrderStatusFilterHides.sql |
+| [Shipping Carriers & Carrier Account Numbers (records, matching, duplication, deletion)](features/shipping-carriers-and-accounts.md) | `ShippingCarriers` is a **per-client** table (one row per carrier, per client DB) that the NetSuite syncs create on demand and that Fulfill & Ship reads to buil | _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ShippingMethod.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, api2/Component/Api/V2/V2.php |
 | [_String helpers — ASCII-safe HTML entity encoding (and the parseBetween trap)](features/string-html-entity-helpers.md) | `_String` is the 2.0 framework's static string utility class. | _underscore/String.php |
 | [Surface FIELD ↔ RecordField binding (maxLength / validationType / isWritable fold-in)](features/surface-field-recordfield-binding.md) | A resolver capability that makes a surface `FIELD` element carry its **input contract** — max length, validator name, and whether the caller may write it — inst | _underscore/Model/Core/Surface.php, _underscore/Model/Core/RecordField.php, _underscore/Model/Core/AclFieldPermission.php, _underscore/Model/Client/RecordFieldSetting.php, _underscore/Model/Client/ClientRecordFieldSetting.php, dbchanges2/Core/2026-08-14c - RecordFieldsValidationMetadata.sql, dbchanges2/Client/2026-08-14a - RecordFieldSettingsClientTable.sql, api2/Component/Api/V2/V2.php |
 | [Surface Resolver (_Model_Core_Surface::resolve — replaces Page::meta)](features/surface-resolver.md) | The runtime for the platform-wide **Surface** UI presentation layer: 9 `_underscore` models plus a cached resolver, `_Model_Core_Surface::resolve(&$api, string | _underscore/Model/Client/Language.php, dbchanges2/Core/2026-08-21 - SalesOrderDecisionSurfacesReseed.sql, dbchanges2/Core/2026-08-24 - RestoreApproveDenyRowActionsVisibility.sql, dbchanges2/Client_Quad/2026-08-24 - ProdPortApprovePoNumberEnabledRule.sql, dbchanges2/Client_Compass/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_CompassCanada/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, toga25-supply/src/App.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/contexts/AuthContext.tsx, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Core/2026-08-21a - SalesOrderDecisionSurfacesReseed.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_Compass/2026-08-04a - ApprovalDetailsAssignedManagerPreferredStage.sql, _underscore/Model/Core/Surface.php, _underscore/Model/Client/AclRecordScript.php, _underscore/Model/Core/RecordScript.php, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Quad/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Client_CompassCanada/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Client_Compass/2026-07-15f - SalesOrderRecordActionsRemoveDeadConfigRuleOverrides.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, _underscore/Model/Core/SurfaceElement.php, _underscore/Model/Core/Action.php, _underscore/Model/Core/Vocabulary.php, _underscore/Model/Core/VocabularyTerm.php, _underscore/Model/Core/Message.php, _underscore/Model/Client/SurfaceOverride.php, _underscore/Model/Client/MessageTranslation.php, _underscore/Model/Client/ThemeToken.php, _underscore/Model/Core/Page.php, api2/Component/Api/V2/V2.php, dbchanges2/Core/2026-08-12a - NavigationSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-12a - NavigationRoleGrants.sql, toga25-supply/surface-layer-guide.md |
 | [Table-View Hyperlink Columns (meta → ACL → computed URL → render)](features/tableview-hyperlink-columns.md) | Any 2.0 table-view column can render its value as a clickable link instead of plain text. | _underscore/Model/Client/TableView.php, _underscore/Model/Client/TrackingNumber.php, api2/Component/Api/V2/V2.php, toga2-supply/src/api/toga.ts, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/formatTableData.tsx, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/convertData.tsx, toga2-supply/src/components/ui/Tables/hooks/useDataTableState.tsx, dbchanges2/Client/2026-07-20 - TrackingNumberHyperlinkAndFieldPermission.sql |
-| [TableView joins (TableViewJoins → SQL) — aliasing, chained multi-hop joins, ACL](features/tableview-joins.md) | `Client_*.TableViewJoins` rows are what let a table view show a column from a table other than its base record. | _underscore/Model/Client/TableView.php, _underscore/Model.php, api2/Component/Api/V2/V2.php, dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql, dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_CompassCanada/2026-08-27a - ItemFulfillmentTableViewsRebuild.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql |
+| [TableView joins (TableViewJoins → SQL) — aliasing, chained multi-hop joins, ACL](features/tableview-joins.md) | `Client_*.TableViewJoins` rows are what let a table view show a column from a table other than its base record. | _underscore/Model/Client/TableView.php, _underscore/Model.php, api2/Component/Api/V2/V2.php, dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql, dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_CompassCanada/2026-08-27a - ItemFulfillmentTableViewsRebuild.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-31a - PurchaseOrdersTableViewRebase.sql |
 | [TogaIQ Gateway Client (_Component_Api_Togaiq) — AI generate/translate from 2.0](features/togaiq-gateway-client.md) | `_Component_Api_Togaiq` is the 2.0 framework's client for the **TogaIQ** (Talos) AI gateway. | _underscore/Component/Api/Togaiq/Togaiq.php, _underscore/ApiRequest.php |
 | [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | api2/Component/Api/V2/V2.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19b - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Growrk/2026-07-13a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Elite/2026-08-17 - FulfillmentTableViews.sql, dbchanges2/Client_Quad/2026-08-26a - BackfillQuadUnitLevelTrackingSingleTn.sql, dbchanges2/Client_Quad/2026-08-26b - BackfillQuadItemLevelTrackingSingleTn.sql, dbchanges2/Client_CompassCanada/2026-08-27a - ItemFulfillmentTableViewsRebuild.sql |
 | [Units for Items for Purchase Orders — Data Structure](features/units-for-items-for-purchase-orders.md) | Describes how unit (serialized inventory) data is linked to sales-order and purchase-order line items behind the `units-for-items-for-purchase-orders` TableView | _underscore/Model/Client/ServiceRequest.php, dbchanges2/Client/2026-08-11a - ServiceRequestsInventoryUnitsTableViews.sql |

package/knowledge/2.0/apps/_underscore/features/calculated-sql-fields.md

@@ -6,10 +6,11 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-26
+updated: 2026-09-01
 owners: [snaredla, jcardinal, bala]
 files:
   - _underscore/Model.php
+  - _underscore/Model/Client/PurchaseOrder.php
   - _underscore/Model/Client/SalesOrder.php
   - _underscore/Model/Client/ServiceRequest.php
   - _underscore/Model/Elite/SalesOrder.php
@@ -210,6 +211,13 @@ characters — that is the standard of evidence for touching a field that runs o
   [save-cascade stored-field deadlocks](./model-save-parent-cascade-stored-field-deadlock.md).
 
 ## Change history
+- 2026-09-01 — Added `_shipTo` to the base `_Model_Client_PurchaseOrder` (`public $_shipTo =
+  self::FIELD_SQL;` + static `_shipTo($table = self::TABLE)` returning a correlated subquery
+  `SELECT Addresses.addressee FROM Addresses WHERE Addresses.id = $table.shipToAddressId`),
+  paralleling `SalesOrders._shipTo`. Registered here via a **`Core.RecordFields`** row (id 2555,
+  recordId 17 `purchase-orders`, type STRING, mirroring `SalesOrders._shipTo` id 626) —
+  i.e. the Core-registration path, not the `CustomRecordFields`-only path this doc shows is also
+  sufficient. Additive and shared: it renders only where a view references it. (jcardinal)
 - 2026-08-26 - Documented **how to override a calculated field for one client / sub-client**: api2
   resolves the model class by `str_replace('_Model_Client_', '_Model_' . $clientIdentifier . '_', ...)`
   (`Component/Api/V2/V2.php`), and because the expression is invoked as

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-24
+updated: 2026-09-01
 owners: [mhammontree, tcox, bala]
 files:
   - test/@Mark/true-80824-fedex-inflate-test.php
@@ -28,6 +28,8 @@ files:
   - _underscore/Cloud.php
 related:
   - ../architecture.md
+  - shipping-carriers-and-accounts.md
+  - address-validation.md
   - field-storage-row-hydration.md
   - recursive-item-fulfillments.md
   - ../../toga2-supply/features/fulfill-and-ship.md
@@ -336,6 +338,54 @@ framework-level note is pending on the `_underscore` architecture doc.
 **unconditionally**, so a *dirty read* (reading a storage field after assigning but before saving)
 still discards the unsaved in-memory value.
 
+## Account association: why a valid credential still fails (resolved 2026-09-01, TRUE-81576)
+
+**Carrier API credentials are GLOBAL; account numbers are PER-CLIENT.** `_Config::fedex(...)` and
+`_Config::ups(...)` read one platform-wide config group (`[fedex]` / `[ups]` in
+`api2/Config/production.ini`) and **neither carries an account number** — that comes only from the
+client's `ShippingCarrierAccountNumbers` row. So **a client's own carrier account works only if the
+carrier has authorised TOGA's API credentials to bill it.** See
+[Shipping Carriers & Carrier Account Numbers](shipping-carriers-and-accounts.md).
+
+**The long-running FedEx `SHIPMENT.ACCOUNTNUMBER.UNAUTHORIZED` failure (`ship/v1/shipments`) was an
+account-association problem, not a code bug.** The FedEx API developer account is
+**`jcardinal@goagilant.com`**, whose credentials live in **1Password** — that is where Fulfill &
+Ship's authorised account ID is configured. Using that account ID **succeeded in production**.
+(Location only — no credential values or account numbers belong in this doc.)
+
+### ⚠ Address-validation success is NOT evidence the Ship API works
+
+The `/addresses/validate` USPS→FedEx→UPS cascade can succeed while `ship/v1/shipments` rejects the
+account: **different carrier API surfaces, separate entitlements.** This is exactly what made a ship
+path that had **never worked in production** look like a regression, and it cost significant
+investigation time. Supporting detail: the config carries **separate
+`tracking_client_id` / `tracking_client_secret`** from the ship credentials, implying tracking and
+shipping are provisioned as **different FedEx projects** — an account attached to the tracking
+project but not the ship project produces exactly this error.
+
+### Two diagnostic shortcuts worth remembering
+
+- **Reaching a FedEx BUSINESS-level error proves the OAuth token was issued.**
+  `Fedex::getAccessToken()` throws `'Invalid FedEx API Response'` on **any non-200** from
+  `/oauth/token`, so a business error means the **credentials are valid** and only the account link
+  is missing.
+- **UPS's equivalent is `"Missing or invalid shipper number"`.** That string exists **nowhere in our
+  codebase** (verified by grep), so it is UPS's own message and proves the account **was
+  transmitted**. Our own guard reads *"A carrier account number is required to generate a shipping
+  label."* (`Model/Client/ItemFulfillment.php` ~L794.)
+
+### Where carrier error history actually lives
+
+- **FedEx has NO outbound log row** — the ship call runs `$api->setLogging(false)`
+  (`Fedex.php` ~L280), deliberate because a successful ship response carries the full base64 label
+  (megabytes).
+- The **inbound** `/v2/item-fulfillments/fedexShipmentApi` call **is** recorded in `Logs.Api`
+  (`responseCode` 200, with the carrier error inside `responsePayload`) — **that is the only complete
+  history of label attempts.**
+- **UPS outbound IS logged** (`direction = OUT`, `hostname LIKE '%ups.com%'`).
+- A carrier failure returns **HTTP 200 with an `error` key in `data`**, so it will **not** show up in
+  a 5xx search.
+
 ## Gotchas / known issues
 
 - **⚠ `[ups] label_format` must be set in EVERY environment's api2 config.** Without it **production
@@ -444,6 +494,16 @@ still discards the unsaved in-memory value.
   bill) — expect a hard error rather than a silently-wrong bill in those cases.
 
 ## Change history
+- 2026-09-01 — TRUE-81576: **resolved the long-standing FedEx `SHIPMENT.ACCOUNTNUMBER.UNAUTHORIZED`** —
+  it was an **account-association** problem, not code. The authorised account ID belongs to the FedEx
+  developer account `jcardinal@goagilant.com` (credentials in **1Password**); using it succeeded in
+  production. Recorded the architecture behind it (carrier **credentials are global**, **account
+  numbers per-client** in `ShippingCarrierAccountNumbers`), the trap that **address-validation success
+  proves nothing about the Ship API** (separate entitlements; separate `tracking_client_*` creds imply
+  separate FedEx projects), the two diagnostic shortcuts (a FedEx *business* error proves the OAuth
+  token issued; UPS's "Missing or invalid shipper number" is UPS's own string, not ours), and where
+  carrier error history actually lives (FedEx: inbound `Logs.Api` only; UPS: outbound logged; failures
+  return HTTP 200). TRUE-80824's gzip-decode fix is what made this error readable at all. (mhammontree)
 - 2026-08-24 — Added **batch tracking-status polling** to the carrier libs for the platform-wide
   [tracking-status refresh](../../worker2/features/tracking-status-refresh.md):
   `Fedex::getStatuses()` (~30/call) and `Usps::getStatuses()` (~10/call), reusing the single-shipment

package/knowledge/2.0/apps/_underscore/features/shipping-carriers-and-accounts.md

@@ -0,0 +1,169 @@
+---
+title: Shipping Carriers & Carrier Account Numbers (records, matching, duplication, deletion)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-09-01
+owners: [mhammontree]
+files:
+  - _underscore/Trait/Netsuite/SalesOrder.php
+  - _underscore/Component/Library/Carriers/Fedex/Fedex.php
+  - _underscore/Component/Library/Carriers/Ups/Ups.php
+  - _underscore/Model/Client/ItemFulfillment.php
+  - _underscore/Model/Client/ShippingMethod.php
+  - library/app/api/toga2.php
+  - worker/crons/toga2/netsuite/common_sync_togasupply.php
+  - toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts
+  - api2/Component/Api/V2/V2.php
+related:
+  - carrier-shipping-labels.md
+  - address-validation.md
+  - ../../toga2-supply/features/fulfill-and-ship.md
+  - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
+  - ../../../clients/growrk/features/shipping-carrier-cleanup.md
+---
+
+## Summary
+
+`ShippingCarriers` is a **per-client** table (one row per carrier, per client DB) that the
+NetSuite syncs create on demand and that Fulfill & Ship reads to build its Carrier dropdown.
+Two independent code paths create carrier rows — the 1.0 worker sync
+(`library/app/api/toga2.php`) and the 2.0 NetSuite sales-order trait
+(`_underscore/Trait/Netsuite/SalesOrder.php`) — and both got the "does it already exist?"
+question wrong in different ways, which produced **runaway duplicate rows** and a
+**blank-named catch-all carrier** in production. TRUE-81576 fixed both.
+
+## Data model
+
+- **`ShippingCarriers`** — `id`, `uuid`, `name`. Rows are auto-created by the syncs.
+- **`ShippingMethods.shippingCarrierId`** — the carrier's ship methods (`code` = the carrier
+  service code, e.g. UPS `03` Ground / `01` Next Day Air).
+- **`ShippingCarrierAccountNumbers`** — `id`, `uuid`, `shippingCarrierId` (FK), `name`,
+  `accountNumber`. **This is the only place a per-client carrier account lives.**
+- `ShippingCarriers.defaultShippingCarrierAccountNumberId` — the client's default account.
+
+### Credentials are GLOBAL; account numbers are PER-CLIENT
+
+Both carrier clients read **one platform-wide config group** — `_Config::fedex(...)` /
+`_Config::ups(...)`, defined as `[fedex]` and `[ups]` in `api2/Config/production.ini` — and
+**neither group contains an account number**. The shipper/account number comes **only** from
+`ShippingCarrierAccountNumbers`. Consequence: **a client's own carrier account only works if the
+carrier has authorised TOGA's API credentials to bill it.** A perfectly valid account number that
+is not linked to our API app fails at ship time. This is the architectural reason behind both the
+FedEx and UPS account failures documented in [carrier shipping labels](carrier-shipping-labels.md).
+
+### No account number means invisible in the UI
+
+The Fulfill & Ship **Carrier dropdown only lists carriers with at least one
+`ShippingCarrierAccountNumbers` row**. A carrier with no account row is unselectable no matter how
+it is configured. (GroWrk has FedEx and UPS accounts and no USPS account, so USPS cannot be
+picked there.)
+
+## Runaway duplicate carriers — root cause (fixed TRUE-81576)
+
+`worker/crons/toga2/netsuite/common_sync_togasupply.php` built
+`$lookupShippingCarrierByClientUuidAndShippingCarrierNameUpper` **only as a by-product of its
+`/shipping-methods` loop**, harvesting each method's parent carrier. **A carrier with ZERO
+shipping methods therefore never entered the lookup.** The invoice sync's
+`!isset($lookup[$name])` check in `library/app/api/toga2.php` (~L3194, fed by
+`App_Misc::getCarrierFromTrackingNumber`) then created the carrier **again** — and the new row
+also had no methods, so it stayed invisible to the next run. **One extra row per sync, forever.**
+
+**The diagnostic that cracked it:** the duplicates were **only USPS and DHL** (17x and 6x on
+GroWrk) — exactly the two carriers with **zero** shipping methods. FedEx (7 methods) and UPS
+(4 methods) had **exactly one row each** and were never duplicated. That asymmetry disproved an
+earlier pagination theory and pointed straight at the lookup's source. Scale found in the sweep:
+GroWrk 28 carriers, NYC Health & Hospitals 100, Compass 98, Quad 11, AIG/Rate/Elite 4.
+
+**Fix:** a paged `GET /shipping-carriers` loop that **seeds the lookup directly**, using the same
+`for ($page = 1, $nextPage = 0; ...)` idiom and `MAX_RECORDS_PER_PAGE_TO_FETCH_FROM_TOGA_API`
+(1000) as the neighbouring lookups. Blank names are skipped — they are unusable as keys.
+
+## A blank-named carrier is a WILDCARD (PHP stripos with an empty needle)
+
+The carrier matcher keys on `stripos($nsShippingMethodName, $carrierName) === 0`. Under PHP 8 an
+**empty needle returns `int(0)`** — verified directly:
+
+```
+php -r 'var_dump(stripos("UPS Ground", ""));'   // int(0)
+```
+
+So a carrier row with a blank `name` **matched every ship-method name** and became a catch-all.
+Compounding it: a blank-named carrier has no account numbers, and the UI filters the dropdown to
+carriers with at least one account — so every method swallowed by the placeholder became
+**unreachable in the UI**. Blank names are now **skipped in both matchers**
+(`Trait/Netsuite/SalesOrder.php` and `library/app/api/toga2.php`). The added `(string)` cast also
+removes a PHP 8.1 null-to-non-nullable deprecation on a null `->name`.
+
+### The skip and the placeholder-reuse MUST ship together
+
+The creation branch used to `POST` a **new** carrier with `name => ''` every time nothing matched,
+instead of reusing the placeholder it created on the previous run. It now reuses the existing
+blank placeholder. **Skipping blank names WITHOUT the reuse would leave the placeholder
+permanently unmatchable and INCREASE row creation.**
+
+### Resolve the placeholder BEFORE the shipping-method lookup
+
+(Found in review by php-reviewer.) *Where* the blank-placeholder fallback is resolved changes
+matching semantics. Resolving it **after** the shipping-method lookup leaves `$shippingCarrier`
+null through that lookup, which (a) drops the `ShippingCarriers` join added by
+`if ($shippingCarrier)` and (b) short-circuits the uuid comparison via
+`is_null($shippingCarrier) || ...`. The lookup then degrades into a **carrier-blind global name
+match** that can bind this NetSuite ship-method id onto a *real* carrier's identically-named
+method (an unmapped "Ground" landing on **UPS Ground**). Resolve the placeholder **before** the
+method lookup so the query stays scoped exactly as before. The `$nsShippingMethodName`
+carrier-prefix strip is unaffected either way (`strlen('')` = 0 was already a no-op).
+
+## An unpaginated V2 list GET SILENTLY TRUNCATES
+
+`api2/Component/Api/V2/V2.php`: `DEFAULT_RECORDS_PER_PAGE = 25`, `MAX_RECORDS_PER_PAGE = 10000`,
+and results come back **ordered by uuid**. There is **no error and no warning** — records simply
+are not in the response.
+
+**Concrete impact:** GroWrk had 30 carriers; **UPS** (uuid `db26a116...`) sorted *after* the
+page-1 cutoff (`d513f1ff...`) and was dropped. UPS was therefore unselectable in the Fulfill &
+Ship carrier dropdown **and** invisible to the 2.0 sync's carrier matcher — which also meant the
+UPS service codes populated under TRUE-80824 (`03` Ground / `01` Next Day Air) were never
+reachable. Compass (98) and NYCHH (100) are 4x over the default and were affected the same way.
+
+**Fix:** `recordsPerPage => 1000` on the `_underscore` carrier lookup; `recordsPerPage: 1000` plus
+`sort: ["name"]` on toga2-supply's `getShippingCarriers()`.
+
+**Convention note (toga2-supply):** the `sort` option is a **flat array of field-name strings**,
+with a `-` prefix for descending (e.g. `sort: ["-dateOrder"]`) — **not** objects like
+`[{ name: "ASC" }]`. `ExtendedOptionsType` is `any`, so **tsc will not catch a wrong shape.**
+
+## Delete-safety — every column that references a carrier
+
+Before deleting a `ShippingCarriers` row in a client DB, check **all** of:
+
+- `TrackingNumbers.shippingCarrierId` (**direct**)
+- `TrackingNumbers.shippingCarrierAccountNumberId`
+- `InvoiceTrackingNumbers.shippingCarrierId`
+- `ShippingMethods.shippingCarrierId`
+- `ShippingCarriers.defaultShippingCarrierAccountNumberId`
+
+**`TrackingNumbers` reaches a carrier BOTH directly and via `shippingMethodId`, so a single-path
+check is not sufficient.** Rows with any reference must be repointed to the canonical carrier
+first. See the [GroWrk carrier cleanup](../../../clients/growrk/features/shipping-carrier-cleanup.md).
+
+## Gotchas / known issues
+
+- **Cleaning duplicates before the fix is deployed is wasted work** — the syncs refill the rows on
+  the next run (every 5 minutes). Deploy first, clean second.
+- Compass (98 carriers) and NYC Health & Hospitals (100) are **not** cleaned yet — separate tasks.
+- The `[fedex]` config group contains a key literally named **`_`** with a 32-character value.
+  Purpose unknown; no reader has been traced.
+
+## Change history
+- 2026-09-01 — TRUE-81576: root-caused and fixed **runaway duplicate `ShippingCarriers`** (the 1.0
+  sync lookup was seeded only from `/shipping-methods`, so a method-less carrier was recreated
+  every run) by seeding from a paged `GET /shipping-carriers`; **skipped blank carrier names in
+  both matchers** (an empty `stripos` needle matches everything) and made the creation branch
+  **reuse** the blank placeholder instead of POSTing a new one; resolved the placeholder **before**
+  the shipping-method lookup to keep that query carrier-scoped; and set `recordsPerPage` on both
+  carrier list GETs after an unpaginated 25-row page silently dropped GroWrk's UPS row.
+  (mhammontree)

package/knowledge/2.0/apps/_underscore/features/tableview-joins.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
-owners: [bala, apeterson]
+updated: 2026-09-01
+owners: [bala, apeterson, jcardinal]
 files:
   - _underscore/Model/Client/TableView.php
   - _underscore/Model.php
@@ -17,6 +17,7 @@ files:
   - dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql
   - dbchanges2/Client_CompassCanada/2026-08-27a - ItemFulfillmentTableViewsRebuild.sql
   - dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql
+  - dbchanges2/Client_Nychh/2026-08-31a - PurchaseOrdersTableViewRebase.sql
 related:
   - ../../api2/features/tableview-field-metadata.md
   - ./page-meta-context-field-settings.md
@@ -193,6 +194,28 @@ grants of any kind — `Records` **351** (`transfer-order-stages`) had none befo
 `Client_Nychh/2026-08-28a`, so the Status column of a brand-new view would have vanished silently.
 Check the joined record's grants before assuming an existing record is grant-covered.
 
+## A third mode: an INNER join to an EMPTY FK returns an EMPTY GRID — not an error
+
+The two `meta()` failures above both throw. There is a third, quieter mode that is **not an
+error at all**: a view loads, the header/meta looks right, and the data grid shows **zero rows**.
+
+Cause: an **INNER** `TableViewJoins` on a foreign-key column that is **unpopulated for that
+tenant** drops every row, because an inner join with no matching parent row returns nothing.
+Confirmed 2026-09-01 on the NYCHH `purchase-orders` view: `Client_Nychh.PurchaseOrders` had **0 of
+175 rows** with a populated `locationId`, so an INNER `Locations` join
+(`Locations.id = PurchaseOrders.locationId`) emptied the whole grid. The meta API looked correct;
+the data API just returned 0 results.
+
+- **The blast radius is per tenant.** The same view can serve fine for a client whose FK is
+  populated and go empty for one whose FK is not — so it reads as "the grid is broken for this
+  client only", exactly like an ACL gap, but the join type is the cause.
+- **Fix / avoid:** for an **optional / possibly-empty** FK, use **LEFT OUTER** (rows survive with
+  nulls in the joined columns) or omit the column entirely. Only use INNER when the FK is
+  guaranteed populated for the tenant.
+- **Check before you add:** verify FK population in the target tenant
+  (`SELECT COUNT(*) ... WHERE <fk> IS NOT NULL`) before choosing INNER. NYCHH's `purchase-orders`
+  ultimately **dropped** the Location (and Ship To) column rather than switch to OUTER.
+
 ## Context RecordFieldSettings are OPTIONAL for a joined column to render
 
 `meta()` looks up `contextRecordFieldId`-scoped settings (`DefaultRecordFieldSettings` plus the
@@ -251,9 +274,19 @@ Core-level reference ids used (identical across all clients and environments): *
   read the missing log row as "the request never happened".
 - **An unused join can already exist.** Confirm before inserting; a duplicate join of the same table
   is what breaks chained joins.
+- **An INNER join to an EMPTY FK empties the whole grid with NO error.** Third failure mode: an
+  inner join on an FK that is unpopulated for the tenant drops every row (meta looks fine, data
+  returns 0). Use LEFT OUTER for an optional FK, or verify FK population before choosing INNER.
 
 ## Change history
 
+- 2026-09-01 — Added a **third `meta()` failure mode that is not an error**: an **INNER** join to a
+  foreign key that is **unpopulated for the tenant** returns an **empty grid** (meta correct, data
+  0 rows), because an inner join with no matching parent row drops everything. Found on NYCHH's
+  `purchase-orders` view — `Client_Nychh.PurchaseOrders` had 0 of 175 rows with a populated
+  `locationId`, so an INNER `Locations` join emptied the grid. Rule: use LEFT OUTER (or omit the
+  column) for an optional/possibly-empty FK, and verify FK population in the target tenant before
+  using INNER. (jcardinal)
 - 2026-08-28 — Separated the **two distinct ways `meta()` 500s**, after Compass Canada's
   `item-fulfillments-for-sales-order(-item)s` views returned 500 while Compass USA's served fine.
   (a) A join pointing at a **deleted `Core.Records` / `Core.RecordFields` row** throws from

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

@@ -6,7 +6,7 @@ project: TOGa Supply
 client: shared
 type: feature
 status: active
-updated: 2026-08-11
+updated: 2026-09-01
 owners: [mhammontree]
 files:
   - _underscore/Trait/Netsuite/SalesOrder.php
@@ -56,6 +56,7 @@ files:
   - _underscore/Component/Library/Carriers/Ups/Ups.php
 related:
   - ../architecture.md
+  - ../../_underscore/features/shipping-carriers-and-accounts.md
   - ../../_underscore/features/carrier-shipping-labels.md
   - ../../_underscore/features/recursive-item-fulfillments.md
   - ../../_underscore/features/netsuite-salesorder-address-phone-sync.md
@@ -402,6 +403,24 @@ the call 403s and returns no label.
 
 ## Gotchas / known issues
 
+- **⚠ The Carrier dropdown silently lost UPS because the list GET was UNPAGINATED (fixed
+  2026-09-01, TRUE-81576).** api2's `DEFAULT_RECORDS_PER_PAGE` is **25** and list results come back
+  **ordered by uuid** — no error, no warning, records just are not there. GroWrk had 30 carriers and
+  **UPS** (uuid `db26a116...`) sorted after the page-1 cutoff (`d513f1ff...`), so UPS was unselectable
+  in the dropdown **and** invisible to the 2.0 sync's carrier matcher, which also made the TRUE-80824
+  UPS service codes (`03` Ground / `01` Next Day Air) unreachable. `getShippingCarriers()` now sends
+  **`recordsPerPage: 1000`** and **`sort: ["name"]`**. Compass (98) and NYCHH (100) were affected too.
+- **⚠ The `sort` option is a FLAT ARRAY OF FIELD-NAME STRINGS**, `-` prefix for descending
+  (`sort: ["-dateOrder"]`) — **not** objects like `[{ name: "ASC" }]`. `ExtendedOptionsType` is `any`,
+  so **tsc will not catch a wrong shape**; it just silently does nothing.
+- **⚠ The Carrier dropdown only lists carriers that have at least one
+  `ShippingCarrierAccountNumbers` row.** A carrier with no account number is invisible regardless of
+  configuration — GroWrk has FedEx and UPS accounts but no USPS account, so USPS cannot be selected.
+- **⚠ Address validation succeeding tells you NOTHING about the Ship API.** `/addresses/validate`
+  (USPS→FedEx→UPS) and `ship/v1/shipments` are different carrier surfaces with separate entitlements;
+  a green address check next to a failing label buy is normal, not a contradiction. See
+  [carrier shipping labels](../../_underscore/features/carrier-shipping-labels.md).
+
 - **⚠⚠ A config-driven validator MUST skip DISPLAY-ONLY fields — this caused a TOTAL production
   submit outage (2026-07-29 → 2026-07-31, all clients).** `DUMMYUPDATESHIPMENTFIELDS.json` contains a
   **display-only section header** (id 31, "Address") with **`valueKey: ""` and `isRequired: true`**.
@@ -820,6 +839,13 @@ not the base `_Model_Client_ItemFulfillment`. Tested with GroWrk; UPS support wa
 for Compass and is not yet in prod.
 
 ## Change history
+- 2026-09-01 — TRUE-81576: **UPS reappeared in the Carrier dropdown.** `getShippingCarriers()` was an
+  unpaginated list GET, so api2's 25-row uuid-ordered default page dropped GroWrk's UPS carrier
+  entirely; now sends `recordsPerPage: 1000` and `sort: ["name"]`. Also documented that the dropdown
+  only shows carriers with a `ShippingCarrierAccountNumbers` row, that the `sort` option is a flat
+  array of field-name strings (typed `any`, so tsc will not catch a wrong shape), and that address
+  validation succeeding is not evidence the Ship API works. Verified in production alongside the
+  GroWrk carrier cleanup. (mhammontree)
 - 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 =

package/knowledge/2.0/standards/backend-php.md

@@ -5,7 +5,7 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-08-29
+updated: 2026-09-01
 owners: [jcardinal, mhammontree, dfranks, bala]
 files: []
 related:
@@ -547,6 +547,11 @@ clients/compass-usa/features/stranded-approval-reassignment.md
 * A whole-file ending flip turns a one-line change into a full-file rewrite in `git diff`, burying the real change, breaking `git blame`, and inviting merge conflicts.
 * **Check before committing:** if `git diff --stat` shows a tiny edit as a near-total rewrite, the endings flipped. Restore them — e.g. for an LF file: `tr -d '\r' < file > file.tmp && mv file.tmp file` — then re-stage.
 
+#### These repos use CRLF line endings — normalise on programmatic writes
+
+A scripted or tool-driven edit that writes LF into a CRLF file produces **mixed line endings** and a
+diff that appears to touch the whole file. Any script that rewrites a source file must preserve CRLF.
+
 #### **Braces**
 
 * Opening braces for classes, methods and control structures (`if`, `else`, `for`, `while`, etc.) should go on the same line.
@@ -752,6 +757,22 @@ re-verify against `Controller/Index.php` before relying on it.
 
 * Always use HTTPS to encrypt data in transit.
 
+### NEVER ship a hardcoded-credential fallback — fail loudly instead
+
+`_underscore/Component/Library/Carriers/Fedex/Fedex.php` `initialize()` carries a "production
+fallback" branch with a **literal `client_id` and `client_secret`**. The sandbox branch above it is
+dead code (`elseif (false && _Environment::isDebugMode())`). The hardcoded `client_id` was verified
+programmatically to be **byte-identical** to the one in `api2/Config/production.ini` — i.e. a **live
+production credential committed to git**.
+
+Per the team security rule, a committed secret is compromised. Required actions:
+1. Remove the fallback branch; throw when the `[fedex]` config group is unset.
+2. Delete the dead `false && ...` sandbox branch.
+3. Rotate the FedEx API key with FedEx.
+
+Rule: **config absence is an error, not a reason to fall back to a baked-in value.** A missing
+config group must throw at startup. Never commit a credential value, in any branch, dead or live.
+
 ## Performance Optimization
 
 ### Caching
@@ -870,6 +891,26 @@ client sending a shallow depth.
   (TRUE-79533) — both read the same starved node. Relevant code: `api2/Component/Api/V2/V2.php`,
   `api2/Controller/Index.php`.
 
+### An unpaginated V2 list GET SILENTLY TRUNCATES — always send `recordsPerPage`
+
+`api2/Component/Api/V2/V2.php`: `DEFAULT_RECORDS_PER_PAGE = 25`, `MAX_RECORDS_PER_PAGE = 10000`.
+Omitting `recordsPerPage` returns only the first 25 rows with **no error and no warning** — the rest
+simply are not there, and the caller cannot tell. **No meaningful ordering is guaranteed**: a
+production response was observed coming back in uuid order, so which rows survive truncation is
+effectively arbitrary and can change as data is added.
+
+- Any list GET used to **build a lookup or populate a dropdown** must set `recordsPerPage`
+  explicitly (1000 is the established value; `MAX_RECORDS_PER_PAGE_TO_FETCH_FROM_TOGA_API` in the
+  1.0 sync) **or** loop pages with the `for ($page = 1, $nextPage = 0; ...)` idiom.
+- Always sort by a **meaningful** field rather than relying on the default.
+- Real cost: GroWrk's UPS carrier sorted past the page-1 cutoff and vanished from the Fulfill & Ship
+  carrier dropdown and from the NetSuite carrier matcher, which also made the UPS service codes
+  added under TRUE-80824 unreachable. Compass (98 carriers) and NYCHH (100) are 4× over the default.
+
+**Frontend note (toga2-supply):** the `sort` option is a flat array of field-name strings with a `-`
+prefix for descending (`sort: ["-dateOrder"]`), **not** objects. `ExtendedOptionsType` is `any`, so
+tsc will not catch a wrong shape — it fails silently.
+
 ### API Versioning
 
 * Implement a new version (ie: `/v1`, `/v2`, `/v3`) when a major API framework is introduced to manage the new API framework without breaking existing clients.
@@ -956,6 +997,16 @@ See: 2.0/apps/worker2/features/cross-account-aws-access.md
 
 ## Change history
 
+- 2026-09-01 — TRUE-81576. Three additions: (1) Security — never ship a hardcoded-credential
+  fallback; the FedEx `initialize()` "production fallback" holds a live `client_id`/`client_secret`
+  byte-identical to `api2/Config/production.ini`, so it must throw on missing `[fedex]` config, the
+  dead `false && ...` sandbox branch must go, and the key must be rotated. (2) API Design — an
+  unpaginated V2 list GET silently truncates at `DEFAULT_RECORDS_PER_PAGE = 25` with no error and no
+  guaranteed ordering; always send `recordsPerPage` (or page the loop) for lookups/dropdowns. Cost:
+  GroWrk's UPS carrier fell off page 1 and disappeared from the Fulfill & Ship dropdown and the
+  NetSuite matcher, stranding the TRUE-80824 service codes. Includes the toga2-supply `sort`
+  flat-string-array note (`ExtendedOptionsType` is `any`, so tsc catches nothing). (3) Code
+  Formatting — programmatic writes must preserve CRLF. (mhammontree)
 - 2026-08-29 — Added a fail-loud cross-reference under **PHP Error Handling**: import/sync/cron
   code that reconciles external data must never catch-and-continue or log-and-skip a record;
   points to the full policy and the NetSuite → TOGa Supply sync data-loss incident recorded in

package/knowledge/clients/growrk/INDEX.md

@@ -2,6 +2,7 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
+| [GroWrk — shipping-carrier cleanup, UPS visibility, and the NetSuite Fulfill-and-Ship punch-out URL](features/shipping-carrier-cleanup.md) | 2.0 | GroWrk (`Core.Clients` id **33**, DB `Client_Growrk`) is where the runaway `ShippingCarriers` duplication was found and fixed (TRUE-81576). | _underscore/Trait/Netsuite/SalesOrder.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts |
 | [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 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/shipping-carrier-cleanup.md

@@ -0,0 +1,81 @@
+---
+title: "GroWrk — shipping-carrier cleanup, UPS visibility, and the NetSuite Fulfill-and-Ship punch-out URL"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: growrk
+type: client-feature
+status: active
+updated: 2026-09-01
+owners: ["mhammontree"]
+files:
+  - _underscore/Trait/Netsuite/SalesOrder.php
+  - library/app/api/toga2.php
+  - worker/crons/toga2/netsuite/common_sync_togasupply.php
+  - toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts
+related:
+  - ../profile.md
+  - ../../../2.0/apps/_underscore/features/shipping-carriers-and-accounts.md
+  - ../../../2.0/apps/_underscore/features/carrier-shipping-labels.md
+  - ../../../2.0/apps/toga2-supply/features/fulfill-and-ship.md
+---
+
+## Summary
+
+GroWrk (`Core.Clients` id **33**, DB `Client_Growrk`) is where the runaway
+`ShippingCarriers` duplication was found and fixed (TRUE-81576). GroWrk carried **28** carrier
+rows — 17 duplicate USPS and 6 duplicate DHL, all with zero shipping methods. The mechanics are
+shared and live in
+[Shipping Carriers & Carrier Account Numbers](../../../2.0/apps/_underscore/features/shipping-carriers-and-accounts.md);
+this doc records what was done to GroWrk's **data** and what is still parked.
+
+## What was done (2026-09-01, production, by hand)
+
+**20 fully-orphaned carrier rows** (zero shipping methods, zero account numbers, zero tracking
+references) were **deleted manually in production**, taking GroWrk from **28 carriers to 8**.
+Immediately after, **UPS became visible and selectable** in the Fulfill & Ship carrier dropdown,
+and the NetSuite phone prefill from TRUE-80824 was confirmed working in the same test.
+
+**Decision (Mark): treated as a one-off — no `dbchanges2` migration was written.** The code fixes
+prevent recurrence, so a migration would only re-run a cleanup that cannot happen again. **Note
+this leaves production ahead of `dbchanges2` for that table.**
+
+## Parked follow-ups (not done in this ticket)
+
+- **Carrier ids 15, 17 and 20 could NOT be deleted.** Each still has **one direct
+  `TrackingNumbers.shippingCarrierId` reference**. Those rows must be repointed to the canonical
+  **USPS (id 3)** first. (Remember `TrackingNumbers` reaches a carrier both directly and through
+  `shippingMethodId` — check both paths.)
+- **GroWrk UPS shipping methods ids 11 and 12** ("Overnight Standard" / "Overnight Priority")
+  still have **NULL `code`**, and both are **FedEx product names sitting on UPS rows**.
+- **Compass (98 carriers) and NYC Health & Hospitals (100) are not cleaned** — separate tasks, and
+  the cleanup must happen **after** this deploy or the rows refill.
+
+## Known issue — the NetSuite "Fulfill and Ship" button opens spglobal.togasupply.com
+
+**Not caused by anything in our repos.** Ruled out during this session:
+
+- **No Fulfill & Ship SuiteScript exists anywhere in the workspace.** The only NetSuite user
+  scripts present are `NetSuite_Prudential_Bridge.js`, two forecast exports, and test-folder junk.
+- **No PHP builds a `/shipment-items` or `/edit-shipment` URL.**
+- **`Core.Domains` is correct for GroWrk** — id **400**, `clientId` 33, `appId` 1,
+  `environmentId` 1 → `https://growrk.togasupply.com`.
+
+The URL is therefore built **inside NetSuite's File Cabinet**. Leading hypothesis: **S&P Global**
+is `Core.Clients` id **4** with `Domains` ids 7-9 and was one of the earliest TOGa Supply tenants,
+so the punch-out was likely built for them first and the target is **hardcoded or read from a
+script parameter that is unset for the GroWrk subsidiary**. Where to look: the script on the Sales
+Order / Item Fulfillment form, its script parameters, and any subsidiary-to-URL custom record.
+
+## Data drift
+
+`Core.Domains` id **403** (`growrk.alpha.togasupply.com`) has **NULL `clientId` AND NULL `appId`**,
+unlike every other GroWrk row. Harmless in production; **it will misbehave on alpha.**
+
+## Change history
+- 2026-09-01 — TRUE-81576: deleted **20 orphaned `ShippingCarriers` rows** in production by hand
+  (28 → 8); UPS became selectable in Fulfill & Ship and the TRUE-80824 phone prefill was confirmed.
+  Recorded the parked items (carrier ids 15/17/20 blocked by direct `TrackingNumbers` references;
+  UPS methods 11/12 with NULL codes and FedEx names), the NetSuite punch-out URL pointing at
+  `spglobal.togasupply.com` (built in NetSuite, not our code), and the NULL `clientId`/`appId` drift
+  on `Core.Domains` id 403. Deliberately **no dbchanges2 migration** — one-off cleanup. (mhammontree)

package/knowledge/clients/growrk/profile.md

@@ -13,12 +13,13 @@ project: _Underscore
 client: growrk
 type: profile
 status: active
-updated: 2026-08-28
+updated: 2026-09-01
 owners: ["rgirish", "mhammontree", "bala", "jcardinal"]
 files: []
 related:
   - clients/growrk/features/transfer-order-flow.md
   - clients/growrk/features/units-netsuite-custom-fields.md
+  - clients/growrk/features/shipping-carrier-cleanup.md
 ---
 
 ## Summary
@@ -38,6 +39,14 @@ module (`dbchanges2/Client_Growrk/_modules.txt`).
 
 ## Gotchas
 
+- **Carrier rows were duplicating every sync and UPS was invisible in Fulfill & Ship** (fixed
+  TRUE-81576, 2026-09-01). 20 orphaned `ShippingCarriers` rows were deleted **by hand in production**
+  (28 → 8) with **no dbchanges2 migration**, so production is ahead of `dbchanges2` for that table.
+  Carrier ids **15/17/20** are still blocked by direct `TrackingNumbers` references. Details:
+  [shipping-carrier cleanup](features/shipping-carrier-cleanup.md).
+- **`Core.Domains` id 403 (`growrk.alpha.togasupply.com`) has NULL `clientId` AND NULL `appId`** —
+  real data drift; harmless in production, will misbehave on alpha.
+
 - **`_Model_Growrk_Unit`'s `c_` columns must physically exist on `Client_Growrk.Units` — in EVERY
   environment, production included.** The model body is empty: it is only
   `extends _Model_Client_Unit` + `use _Trait_Netsuite_Unit`, and **the trait** declares all seven

package/knowledge/clients/nychh/INDEX.md

@@ -6,4 +6,4 @@
 | [NYCHH NetSuite → TransferOrders import (stocking-flag routing, PO bridges, origin location)](features/netsuite-transfer-order-import.md) | 1.0 | NYCHH's NetSuite **transfer orders are represented as NetSuite sales orders** (same as the GroWrk pattern), so the shared NetSuite → TOGa Supply importer (`App_ | library/app/api/toga2.php, library/app/api/netsuite/rest.php, library/app/netsuite.php, worker/crons/toga2/netsuite/sync_togasupply_hh.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/diagnose_hh_stuck_transfer_order.php, dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql, dbchanges2/Client/2026-08-28a - TransferOrderItemsTimestampColumns.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestampColumnsReposition.sql, dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql, dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.sql |
 | [NYCHH PO links are UPSTREAM — the downstream SO→PO route returns empty](features/po-number-upstream-direction.md) | 2.0 | NYCHH's sales orders are created **from the customer's purchase order**, so their SO↔PO links live in the **upstream** table `PurchaseOrders_SalesOrders` (route | _underscore/Model/Client/SalesOrder.php, _underscore/Trait/Netsuite/SalesOrder.php, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts, dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql, dbchanges2/Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql |
 | [NYCHH transfer-order 2.0 model — inventory quantities + V2 field enablement](features/transfer-order-inventory-quantities.md) | 2.0 | The 2.0 (`_underscore`) side of NYCHH transfer-order support: a **two-branch inventory quantity model** on the NYCHH `Item` override, plus the **client-override | _underscore/Model/Nychh/Item.php, _underscore/Model/Nychh/PurchaseOrderItem.php, _underscore/Model/Nychh/TransferOrder.php, _underscore/Model/Nychh/TransferOrderStage.php, _underscore/Model/Client/TransferOrder.php, _underscore/Model/Client/TransferOrderItem.php, dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql, dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql |
-| [NYC Health & Hospitals](profile.md) | 2.0 | NYC Health & Hospitals (NYCHH) is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Nychh`. | dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql |
+| [NYC Health & Hospitals](profile.md) | 2.0 | NYC Health & Hospitals (NYCHH) is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Nychh`. | dbchanges2/Client_Nychh/2026-08-31a - PurchaseOrdersTableViewRebase.sql, dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql |

package/knowledge/clients/nychh/profile.md

@@ -16,9 +16,10 @@ project: _Underscore
 client: nychh
 type: profile
 status: active
-updated: 2026-08-31
+updated: 2026-09-01
 owners: ["jcardinal", "apeterson", "bala", "akhokhani"]
 files:
+  - dbchanges2/Client_Nychh/2026-08-31a - PurchaseOrdersTableViewRebase.sql
   - dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql
   - dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql
   - dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql
@@ -48,6 +49,19 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   run the NetSuite→TOGa Supply sync and the asset-tag verification/backfill diagnostics.
 
 ## Key features (this client)
+- **`purchase-orders` table view was rebased off the wrong record (2026-09-01).** The view was
+  based on **SalesOrders (Core record 14)** but had to be **PurchaseOrders (record 17)** — it was
+  mislabeled. `Client_Nychh/2026-08-31a - PurchaseOrdersTableViewRebase.sql` flips
+  `TableViews.recordId` 14→17, drops the SalesOrders→bridge→PurchaseOrders join chain, removes the
+  "Sales Order number" column (`SalesOrders.number`, RecordFields 49), and repoints the rest to PO
+  fields — final columns **number (base field 87), dateOrder (86), total (`_total` 1429)**. Location
+  and Ship To were intentionally **omitted**: PO `locationId` is empty for this tenant, so an INNER
+  Locations join would empty the grid (see the third failure mode in
+  [tableview-joins](../../2.0/apps/_underscore/features/tableview-joins.md)). The migration also
+  seeds a **Developer-role (role 2)** record ACL grant chain (`AclRecordPermissions` →
+  `AclLogicGroups` → `AclLogicGroupExpressions`, reusing record 17's `all` expression) and reads
+  `AclFieldPermissions` for the displayed fields, resolving `roleId` by role **name**. Written
+  idempotent / uuid-keyed; applied to **prod and client-sandbox**.
 - **`inventory_units` table view carries item detail as of 2026-08-18** — Part Number, Manufacturer
   and Item Description sit directly after Asset Tag, reached through a **chained** Units → Items →
   Manufacturers join (`dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql`, identical
@@ -112,6 +126,8 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   [NYCHH PO Number direction](./features/po-number-upstream-direction.md).
 
 ## Notes
+- **Role ids in `Client_Nychh` (verified 2026-09-01):** `1 = Base`, `2 = Developer`, `3 = API`.
+  Role ids differ per client DB — resolve by **name** in migrations, never hard-code these.
 - **PO Number is upstream-sourced** (`PurchaseOrders_SalesOrders`), which is why the downstream
   SO→PO route and the shared `_purchaseOrders` field came back empty. Details, and the
   now-closed-on-`_beta` fix: [NYCHH PO Number](./features/po-number-upstream-direction.md).

package/package.json

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