toga-ai 1.0.723 → 1.0.725

package/knowledge/1.0/apps/worker/workflows/netsuite-duplicate-items-dedup.md

@@ -111,13 +111,27 @@ duplicates** and must be deployed first — see
 - **`UPDATE IGNORE ...; DELETE ... WHERE fk=dupe` permanently DELETES collision rows** and drops its
   helper maps, so prod cannot self-reverse. A reversal needs a **pre-merge snapshot** restored as a
   scratch DB — plan the backup before running any variant of this.
-- **Blast radius of the 2026-08-31 `duplicate_items_merge_ALL_CLIENTS.sql`:** it ran on 17 clients
-  (Masonite, Ncci, Erau, Shrss, Wmchealth, Trividiahealth, Prudential, Miamidade, Browardsheriff,
-  Nychh, Canon, Quad, Compass, Elite, Growrk, Spglobal, Endeavorhealth). At-risk = two-catalog +
-  TOGa Commerce clients like Compass; a **per-client assessment is outstanding**.
+- **Blast radius of the 2026-08-31 `duplicate_items_merge_ALL_CLIENTS.sql` (assessment complete
+  2026-09-01):** it ran on 17 clients (Masonite, Ncci, Erau, Shrss, Wmchealth, Trividiahealth,
+  Prudential, Miamidade, Browardsheriff, Nychh, Canon, Quad, Compass, Elite, Growrk, Spglobal,
+  Endeavorhealth). **Only 2 were damaged — Compass and Quad, both two-catalog TOGa Commerce
+  clients.** The other 15 needed no reversal: 13 single-catalog "Agilant"-only clients were a
+  legitimate within-catalog dedup, NYCHH mixed Etilize + NetSuite in one catalog (no fold
+  possible), and Prudential was cleared (single populated catalog; NULL `assetType` is its normal
+  state). Triage per client with `Catalogs` LEFT JOIN `Items` (empty catalogs still show) + the
+  pipeline signal (`c_etilizeProductId` = store vs `c_netsuiteInternalItemId` = Agilant); a client
+  is damaged only if it has a two-catalog store/procurement design AND catalog-1 was folded into
+  catalog-2 AND storefront/transmit depends on catalog-1. See the Compass
+  [catalog-fold reversal](../../../clients/compass-usa/workflows/catalog-fold-reversal.md) and
+  [Quad catalog-fold reversal](../../../clients/quad/workflows/catalog-fold-reversal.md).
 
 ## Change history
 
+- 2026-09-01 — **Blast-radius assessment complete.** Of the 17 clients the merge ran on, only 2
+  were damaged — Compass and Quad (both two-catalog TOGa Commerce). The other 15 needed no
+  reversal (13 single-catalog "Agilant"-only = legitimate within-catalog dedup; NYCHH mixed
+  Etilize + NetSuite in one catalog; Prudential cleared — single populated catalog, NULL
+  assetType is normal). Added the durable triage method and linked the Quad reversal. (jcardinal)
 - 2026-09-01 — **⚠ Corrected the success claim.** "0 duplicate part numbers" is NOT a clean-run proof
   for a multi-catalog client. This merge is catalog-blind (groups on `UPPER(partNumber)` only), so for
   Compass it folded 199 intentional catalog-1 store items into their Agilant canonical, broke MITS

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 |
@@ -46,7 +46,7 @@
 | [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/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/INDEX.md

@@ -18,7 +18,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 73 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 75 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 58 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 25 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 15 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/knowledge/clients/compass-usa/workflows/catalog-fold-reversal.md

@@ -95,19 +95,46 @@ damage.**
 - **Never `UPDATE IGNORE` + delete-leftover for a catalog operation** — it permanently deletes
   collision rows and cannot be reversed. Use FK-checks-ON, fail-loud, single transaction.
 
-## Blast radius — other clients (OUTSTANDING)
+## Blast radius — other clients (ASSESSMENT COMPLETE)
 
 The `duplicate_items_merge_ALL_CLIENTS.sql` ran `USE Client_<X>` on **17 clients**: Masonite,
 Ncci, Erau, Shrss, Wmchealth, Trividiahealth, Prudential, Miamidade, Browardsheriff, Nychh,
 Canon, Quad, **Compass**, Elite, Growrk, Spglobal, Endeavorhealth.
 
-- **Not all are damaged.** The NYCHH run was a legitimate dedup.
-- **At-risk = clients with the two-catalog + TOGa Commerce setup like Compass.** A per-client
-  assessment (customer-scoped, rehearsed) is **outstanding for a future session**.
+**Verdict (assessment complete 2026-09-01): only 2 of 17 were damaged — Compass (reversed prior
+session) and Quad. The other 15 needed no reversal.**
+
+- **13 single-catalog "Agilant"-only clients** (Masonite, Ncci, Erau, Shrss, Wmchealth,
+  Trividiahealth, Miamidade, Browardsheriff, Canon, Elite, Growrk, Spglobal, Endeavorhealth):
+  the merge was a **legitimate within-catalog dedup** — no reversal needed.
+- **NYCHH:** confirmed the legit-dedup pilot — one catalog "Agilant" mixing 221 Etilize +
+  NetSuite items in the **same** catalog, so no cross-catalog fold was possible.
+- **Prudential: CLEARED** — all 50k+ order lines were always on its single populated "Agilant"
+  catalog; its "USA"/"India"/"Ireland" catalogs are empty placeholders; uniform NULL-`assetType`
+  is its **normal** state, not damage.
+- **Quad: DAMAGED** — a two-catalog TOGa Commerce client like Compass, but the damage was
+  **storefront-only** (not an order-transmission outage). Reversed with a self-contained
+  sandbox-sourced patch. See the
+  [Quad catalog-fold reversal](../../quad/workflows/catalog-fold-reversal.md).
 - **Compass Canada was NOT damaged and is structurally immune** — it was not in the merge's
   client list, has a single catalog, and does not use NetSuite (so no dupe-item bug).
 
+**Triage method (durable).** Per `Client_<X>`, compare `Catalogs` LEFT JOIN `Items` (so EMPTY
+catalogs still show) with item counts per catalog plus the pipeline signal
+(`c_etilizeProductId` = Etilize/store vs `c_netsuiteInternalItemId` = NetSuite/Agilant). A
+client is **DAMAGED only if** it has an intentional two-catalog store/procurement design **AND**
+catalog-1 items were folded into catalog-2 **AND** storefront/transmit depends on catalog-1.
+NULL-`assetType` order lines alone are **not** damage (Prudential and Quad show that as normal).
+
 ## Change history
+- 2026-09-01 — **Blast-radius assessment complete.** Resolved the outstanding per-client
+  assessment: only **2 of 17** clients were damaged — Compass (reversed prior session) and Quad
+  (storefront-only, reversed this session). The other 15 needed no reversal: 13 single-catalog
+  "Agilant"-only clients were a legitimate within-catalog dedup, NYCHH mixed Etilize + NetSuite
+  in one catalog (no fold possible), and Prudential was cleared (single populated catalog; NULL
+  assetType is its normal state). Added the durable triage method (Catalogs LEFT JOIN Items +
+  per-catalog pipeline signal) and the damaged-only test. See the
+  [Quad catalog-fold reversal](../../quad/workflows/catalog-fold-reversal.md). (jcardinal)
 - 2026-09-01 — Recorded the root cause of the Compass MITS outage: the ad-hoc cross-client
   `duplicate_items_merge_ALL_CLIENTS.sql` (2026-08-31 ~12:43) folded 199 Compass catalog-1
   store items into their Agilant canonical, producing MITS HTTP 400 (NULL assetType) and SQL

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/knowledge/clients/quad/INDEX.md

@@ -6,3 +6,4 @@
 | [Quad multi-currency item prices & vendor item costs](features/multi-currency-item-pricing.md) | 2.0 | Quad prices the **same item in several currencies** and costs the **same vendor item in the vendor's own currency**, so both listings must show a *set* of amoun | _underscore/Model/Quad/Item.php, _underscore/Model/Quad/VendorItem.php, toga2-supply/src/components/ui/CurrencyAmountLines.tsx, toga2-supply/src/pages/Items/api/itemsApi.ts, toga2-supply/src/pages/VendorItems/api/vendorItemsApi.ts, toga2-supply/src/pages/VendorItems/VendorItemsPage.tsx, dbchanges2/Client_Quad/2026-08-24 - Quad Multi Currency Item Pricing.sql, worker/crons/toga2/quad/Imports/import_items.php |
 | [Quad: PO + ASN email importer (import_po_and_asn.php)](features/po-asn-email-import.md) | 1.0 | Quad Graphics' supplier emails Purchase Order and Advance Shipping Notice CSVs into a monitored Microsoft 365 mailbox. | worker/crons/toga2/quad/import_po_and_asn.php |
 | [Quad Graphics](profile.md) | 2.0 | Quad Graphics is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Quad`. |  |
+| [Quad Graphics — reversing the 30-item catalog fold (storefront-assortment recovery)](workflows/catalog-fold-reversal.md) | 2.0 | Quad is the **second and only other** client damaged by the 2026-08-31 catalog-blind `duplicate_items_merge_ALL_CLIENTS.sql`. | test/team/2.0 deployment/quad_catalog_fold_reversal.sql, test/team/2.0 deployment/duplicate_items_merge_ALL_CLIENTS.sql, worker/crons/toga2/quad/workflow/1_transmit_purchase_orders_to_vendors.php |

package/knowledge/clients/quad/profile.md

@@ -16,10 +16,11 @@ project: _Underscore
 client: quad
 type: profile
 status: active
-updated: 2026-08-26
+updated: 2026-09-01
 owners: ["jcardinal", "bala", "apeterson", "ajean"]
 files: []
 related:
+  - ./workflows/catalog-fold-reversal.md
   - ./features/po-asn-email-import.md
   - ./features/enter-po-details-vendor-selection-ev12.md
   - ../../2.0/apps/_underscore/features/sales-order-po-number-sourcing.md
@@ -134,4 +135,11 @@ Client-specific DB change-sets live in `dbchanges2/Client_Quad/`.
   `acl['vendor-items']['navigation-edit-on-vendor-items']` (`Core.AclActions` id 7 on record 19);
   Quad had id 5 only. Granted id 7 to role 7 (Global Admin). UI gate only — record 19 already
   granted role 1 full CRUD.
+- **Two-catalog TOGa Commerce client (like Compass).** Catalog 1 "Quad" = storefront (Etilize,
+  carries `assetType`); catalog 2 "Agilant" = procurement (NetSuite, NULL `assetType`). Unlike
+  Compass, the storefront customer `customerId = 8` has its **orders on Agilant by design**, so
+  the "Quad" catalog is display-only. This is why the 2026-08-31 catalog-blind merge damaged
+  Quad's **storefront only** (not orders/transmit), and Quad was the **only other client besides
+  Compass** that needed a reversal. See
+  [Quad catalog-fold reversal](./workflows/catalog-fold-reversal.md).
 - This profile is a starting point; expand as more Quad-specific behavior is captured.

package/knowledge/clients/quad/workflows/catalog-fold-reversal.md

@@ -0,0 +1,130 @@
+---
+title: Quad Graphics — reversing the 30-item catalog fold (storefront-assortment recovery)
+framework: "2.0"
+project: _Underscore
+client: quad
+type: workflow
+status: active
+updated: 2026-09-01
+owners: ["jcardinal"]
+files:
+  - test/team/2.0 deployment/quad_catalog_fold_reversal.sql
+  - test/team/2.0 deployment/duplicate_items_merge_ALL_CLIENTS.sql
+  - worker/crons/toga2/quad/workflow/1_transmit_purchase_orders_to_vendors.php
+related:
+  - ../../compass-usa/workflows/catalog-fold-reversal.md
+  - ../../compass-usa/features/item-catalogs-and-duplicate-items.md
+  - ../../../1.0/apps/worker/workflows/netsuite-duplicate-items-dedup.md
+  - ../profile.md
+---
+
+## Summary
+
+Quad is the **second and only other** client damaged by the 2026-08-31 catalog-blind
+`duplicate_items_merge_ALL_CLIENTS.sql`. Like Compass, Quad is a **two-catalog TOGa Commerce**
+client, so the merge folded catalog-1 store items into their catalog-2 Agilant twins. But
+**Quad's damage shape is different from Compass's** — it was **storefront-only**, not an
+order-transmission outage. This workflow records the damage and the self-contained reversal.
+See the [Compass catalog-fold reversal](../../compass-usa/workflows/catalog-fold-reversal.md)
+for the shared playbook this refines.
+
+## Quad's catalog model (why the merge damaged it)
+
+- **Catalog 1 "Quad"** — the storefront catalog. Etilize/store items, carries
+  `assetType`/classification.
+- **Catalog 2 "Agilant"** — the procurement catalog. NetSuite items, **NULL `assetType`**.
+- **`customerId = 8` IS the Quad storefront customer, but its ORDER LINES correctly resolve to
+  catalog-2 Agilant** (verified identical prod vs client-sandbox: ~8040 Agilant / 8 Quad on
+  both sides). So Quad's customer→catalog rule **differs from Compass**: the store customer's
+  *orders* live on Agilant; the "Quad" catalog is **storefront display**. This is why orders
+  were **not** damaged for Quad, unlike Compass (whose store customer belonged on catalog-1 and
+  whose MITS transmit broke).
+
+## What broke — storefront only
+
+The merge deleted **30 catalog-1 "Quad" store items** (each had an Agilant `partNumber` twin)
+and re-pointed their references onto **NULL-`assetType` Agilant** items. Corrupted storefront
+references:
+
+- **48** `AssortmentItems` tiles
+- **1185** `ItemFeatures`
+- **49** `ItemPrices`
+- **79** `ItemImages`
+- **32** `Personas_Items`
+- **49** `VendorItems`
+- **1** `SalesOrderItem`
+
+**What did NOT break:**
+
+- **Orders** — `customerId = 8` lines were already on Agilant by design (see catalog model).
+- **PO → vendor transmit** (`worker/crons/toga2/quad/workflow/1_transmit_purchase_orders_to_vendors.php`)
+  — multi-vendor items went **DOWN 176 → 154** (the merge reduced them; no VendorItem fusion,
+  so no SQL 1242 exposure — contrast Compass).
+
+**Source of truth for the correct state = a client-sandbox copy of `Client_Quad`** (id-space
+aligned with prod, verified): 100% of `AssortmentItems` sit on catalog "Quad"; prod had 48
+wrongly on Agilant. No recent prod backup existed.
+
+## The reversal (self-contained, sandbox-sourced)
+
+Deliverable: `test/team/2.0 deployment/quad_catalog_fold_reversal.sql` — rehearsed,
+CTO-reviewed (**AGREE**), applied to prod.
+
+1. **Reinsert the 30 deleted catalog-1 `Items` verbatim from the sandbox at their original
+   ids.** The patch is **self-contained** — no cross-DB references; the sandbox rows are
+   inlined.
+2. **Move the merge-relocated child rows back off the Agilant canonical** by one of two proven
+   mechanisms:
+   - **(a) Precise move by row `uuid`** — for tables whose canonical (Agilant) item
+     legitimately keeps its **own** native/sibling rows: `ItemImages`, `VendorItems`,
+     `SalesOrderItems`, and (after CTO review) `AssortmentItems`, `ItemPrices`,
+     `Personas_Items`. Moving by uuid touches only the rows that were actually relocated.
+   - **(b) Map-move** (`itemId` canon→dupe via a dupe→canon map) — used **ONLY for
+     `ItemFeatures`**, safe by a data-model invariant: **nothing writes `ItemFeatures` onto
+     catalog-2 items** (the Etilize feed targets catalog-1; NetSuite creates catalog-2 items
+     with no features; the sync is stopped; sandbox canon-native `ItemFeatures` = 0).
+   - **`VendorItemCosts` ride along unchanged** (VendorItems are moved, not deleted).
+
+## Safety model (refines the Compass playbook)
+
+- **Single transaction, `FOREIGN_KEY_CHECKS = 1`, NO `UPDATE IGNORE`, `COMMIT` left
+  commented.**
+- **8 fail-loud CASE-based guards** — abort via a subquery-returns-row → forced error 1242.
+- **Row-count-conservation guards** using pre-run `@vars`.
+- **A preflight PK-absence guard.**
+- **Rehearsed on a LOCAL `Client_Quad` freshly restored from prod** — repeatable because the
+  commented `COMMIT` + rollback-on-disconnect leaves the DB unchanged.
+- **Perturbation-tested** — pre-inserted a restore id and confirmed the preflight guard aborts.
+- **CTO review drove the hardening** of the four blind guards from count-equality to
+  identity-based uuid moves.
+
+## Critical rules / gotchas
+
+- **NULL `assetType` on order lines ALONE is NOT proof of catalog-fold damage.** Quad (and
+  Prudential) show 100% NULL-`assetType` Agilant order lines as their **normal** state. Damage
+  requires the two-catalog store/procurement split **AND** storefront/transmit dependence on
+  catalog-1.
+- **The merge's damage is client-specific in SHAPE.** Compass = order-transmission break (MITS
+  HTTP 400 / SQL 1242); Quad = storefront-assortment corruption only. **Assess each client's
+  actual dependency; do not assume Compass's failure mode.**
+- **MySQL reversal/rehearsal mechanics:**
+  - Temp-table `uuid` columns need `COLLATE utf8mb4_unicode_ci` (or an explicit COLLATE on the
+    join) to match the real tables.
+  - A `TEMPORARY` table **cannot be referenced twice in one query** — inline id-lists in guards
+    instead.
+  - A `QUOTE()`-generated multi-row `INSERT` can **silently drop a trailing field** for rows
+    with several trailing NULLs — **validate field counts before running.**
+
+## Change history
+
+- 2026-09-01 — Recorded Quad as the second (and only other) client damaged by the catalog-blind
+  `duplicate_items_merge_ALL_CLIENTS.sql`. Documented Quad's two-catalog model (store customer
+  `customerId=8` orders live on Agilant by design, so orders were NOT damaged — unlike Compass),
+  the storefront-only damage (30 deleted catalog-1 items; 48 AssortmentItems / 1185 ItemFeatures
+  / 49 ItemPrices / 79 ItemImages / 32 Personas_Items / 49 VendorItems / 1 SalesOrderItem
+  re-pointed onto NULL-assetType Agilant), and the self-contained sandbox-sourced reversal
+  (`quad_catalog_fold_reversal.sql`): reinsert 30 items verbatim at original ids, then move child
+  rows back by uuid (precise) or by map (ItemFeatures only, safe by the no-features-on-catalog-2
+  invariant). Safety model: single transaction, FK-checks ON, no UPDATE IGNORE, 8 fail-loud CASE
+  guards, count-conservation guards, preflight PK guard; rehearsed on a prod-restored local,
+  perturbation-tested, CTO-reviewed AGREE. (jcardinal)

package/package.json

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