toga-ai 1.0.652 → 1.0.653

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

@@ -37,8 +37,8 @@
 | [Persona Name Translation (PersonaTranslations sidecar)](features/persona-name-translation.md) | Serves Persona **names** in multiple languages by adding a per-language **sidecar** table `PersonaTranslations`, reusing the platform's existing metadata-driven | _underscore/Model/Client/PersonaTranslation.php, dbchanges2/Client/2026-07-22b - PersonaTranslations.sql, dbchanges2/Core/2026-07-22a - PersonaTranslationsRecord.sql, dbchanges2/Client/2026-07-22c - PersonaTranslationsAcl.sql, dbchanges2/Client_CompassCanada/2026-07-22 - PersonaTranslationsFrench.sql, toga2-commerce/src/pages/Account/view/MySettingsView.tsx |
 | [Record Change Audit Log (Logs_<Client>.Record / RecordField) — reading a field's history](features/record-change-audit-log.md) | Every 2.0 client schema has a sibling **logs** schema `Logs_<Tenant>` (e.g. | _underscore/Model/Client/Logs/Record.php, _underscore/Model/Client/Logs/RecordField.php, _underscore/Model/Client/Logs/CustomRecordField.php |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql, dbchanges2/Client_Compass/2026-08-18 - FixSA135471HeroItemHalfQuantityFulfillment.sql |
-| [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, 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 |
+| [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 |
 | [_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 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 |

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

@@ -23,7 +23,7 @@ related:
   - ../../api2/features/v2-api-error-codes.md
   - ./model-magic-field-access.md
   - ./model-save-parent-cascade-stored-field-deadlock.md
-  - ./purchase-order-sales-order-bridges.md
+  - ./sales-order-purchase-order-bridge-direction.md
 ---
 
 ## Summary
@@ -186,7 +186,7 @@ generous end; `Developer` and `Public` get no ACL row for any field.
   `Client_Imhouston` (1 of 35 prod) and 7 of 36 client-sandbox schemas, driving the re-runnable
   `Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql`. Recorded the `Base` + `API`
   by-name ACL convention for these rows. Cross-linked
-  [PO-to-SO bridge tables](./purchase-order-sales-order-bridges.md) — the metadata row makes
+  [PO-to-SO bridge tables](./sales-order-purchase-order-bridge-direction.md) — the metadata row makes
   `_purchaseOrders` *requestable*, but the field's SQL was reading the wrong bridge table, so a
   successful rollout still returned blank for most clients. (bala)
 - 2026-08-18 - Documented **how a calculated field becomes requestable**: a client-scoped

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

@@ -16,7 +16,7 @@ related:
   - acl-permission-chain.md
   - address-uniqueness-normalization.md
   - carrier-shipping-labels.md
-  - purchase-order-sales-order-bridges.md
+  - sales-order-purchase-order-bridge-direction.md
   - ../../toga2-supply/features/fulfill-and-ship.md
   - ../../api2/features/record-scripts.md
 ---
@@ -41,15 +41,16 @@ changes behaviour for all 22 clients at once**.
 (and was NULL on the order tested), while the **bridge covers 12,643 of 12,658** orders. Resolve the
 PO through the bridge, not the column.
 
-**⚠ …and it is the REVERSE bridge, which the shared `SalesOrders._purchaseOrders` field did not
-read.** This trait writes the PO link via the api2 child key **`purchaseOrderSalesOrders`**, which
-lands in **`PurchaseOrders_SalesOrders`** — while the base calculated field
-`_Model_Client_SalesOrder::_purchaseOrders()` queried **`SalesOrders_PurchaseOrders`**, a *different*
-table populated by a *different* (1.0 cron) pipeline holding Agilant's **vendor** POs rather than the
-customer's. So every client on this trait stored a correct PO that the field could not see: 41,381 of
-72,134 prod orders rendered blank. Read
-[PO-to-SO bridge tables](./purchase-order-sales-order-bridges.md) **before** touching either side of
-this link — the child key you choose decides which table you write, silently.
+**⚠ …and it is the UPSTREAM bridge, which the shared `SalesOrders._purchaseOrders` field did not
+read.** This trait writes the PO link via the api2 child key **`purchaseOrderSalesOrders`**, landing
+in **`PurchaseOrders_SalesOrders`** (upstream — the *customer's* PO). The base calculated field
+`_Model_Client_SalesOrder::_purchaseOrders()` queried **`SalesOrders_PurchaseOrders`** (downstream),
+a *different* table populated by a *different* pipeline — the 1.0
+`App_Api_Toga2::syncPurchaseOrderFromNetsuite` cron — holding Agilant's **vendor** POs. So every
+client on this trait stored a correct PO the field could not see: **41,381 of 72,134** prod orders
+rendered blank until a downstream-then-upstream `COALESCE` was added. Read
+[SO↔PO bridge direction](./sales-order-purchase-order-bridge-direction.md) **before** touching either
+side of this link — the child key you choose decides which table you write, silently.
 
 ## ⚠ Four traps when writing a field on this shared trait
 
@@ -102,11 +103,11 @@ intended, not a fault.
 ## Change history
 
 - 2026-08-26 — Corrected the PO half of the "where the values come from" table: the
-  `purchaseOrderSalesOrders` child key this trait posts writes the **reverse** bridge
+  `purchaseOrderSalesOrders` child key this trait posts writes the **upstream** bridge
   (`PurchaseOrders_SalesOrders`, customer PO), while the shared `SalesOrders._purchaseOrders`
-  calculated field read the **forward** bridge (`SalesOrders_PurchaseOrders`, Agilant vendor PO) — so
+  calculated field read the **downstream** bridge (`SalesOrders_PurchaseOrders`, Agilant vendor PO) — so
   all 22 trait clients stored a PO the UI could not display (41,381 of 72,134 prod orders blank).
-  Cross-linked the new [PO-to-SO bridge tables](./purchase-order-sales-order-bridges.md) doc. (bala)
+  Cross-linked [SO↔PO bridge direction](./sales-order-purchase-order-bridge-direction.md). (bala)
 - 2026-08-11 — TRUE-80824: created. Prefilled TOGa Supply's Reference 1 / Reference 2 / Phone # from
   NetSuite by sourcing `SalesOrders.number`, the bridge-linked purchase order (`otherRefNum` — **not**
   `customerPurchaseOrder`, ~59% populated vs the bridge's 12,643/12,658), and the shipping address's

package/knowledge/2.0/apps/_underscore/features/sales-order-po-number-sourcing.md

@@ -6,11 +6,13 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-25
-owners: [apeterson]
+updated: 2026-08-26
+owners: [apeterson, bala]
 files:
   - _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
@@ -50,12 +52,53 @@ deliberately **not** set: the value is a scalar comma-joined string, not a perso
 via `resolvePathInsensitive(valueKey)`, normalising an empty string to an em-dash.
 
 ### The tenant layer (`_purchaseOrders`)
+
+**Only TWO classes in the whole tree define this method** — verified with
+`grep -rn "function _purchaseOrders" _underscore/`:
+
 | Tenant | Implementation | Direction read |
 |---|---|---|
-| **Compass USA** | overrides in `_underscore/Model/Compass/SalesOrder.php:238` — a `UNION ALL` of its own vendor POs plus Office Depot's POs traversed SO→PO→SO→PO across the multi-tier chain | downstream **+ upstream** (only tenant reading upstream) |
-| **Quad Graphics** | no override → base implementation | downstream only |
-| **Compass Canada** | no `Model/Compasscanada/` directory exists at all → base implementation | downstream only |
-| base (`_Model_Client_SalesOrder:348`) | the shared calculated field | **downstream only** (`SalesOrders_PurchaseOrders`) |
+| **Compass USA and Compass Canada** | both inherit `_Model_Compass_SalesOrder::_purchaseOrders()` (`_underscore/Model/Compass/SalesOrder.php:238`) — a `UNION ALL` of its own vendor POs plus Office Depot's POs traversed SO→PO→SO→PO across the multi-tier chain | downstream **+ upstream** |
+| **Quad Graphics** | no override → base implementation | downstream, then upstream fallback |
+| base (`_Model_Client_SalesOrder:349`) | the shared calculated field | **downstream, falling back to upstream** (see below) |
+
+**⚠ Correction (2026-08-26): Compass Canada is not on the base implementation.** The earlier "no
+`Model/Compasscanada/` directory" reading looked in the wrong place — Compass's tenants nest one
+level deeper, at `_underscore/Model/Compass/Canada/SalesOrder.php`, where
+`_Model_Compass_Canada_SalesOrder extends _Model_Compass_SalesOrder`. Compass USA is
+`Model/Compass/Usa/SalesOrder.php` and does the same. So **any change to the Compass override moves
+both Compass tenants**, and neither is affected by a change to the base. Compass Canada's upstream
+bridge is in fact **empty** (0 rows; 735 of 788 orders resolve downstream) — it is downstream-only,
+not upstream-only.
+
+### The base field now falls back to upstream (`COALESCE`)
+
+Because the trait-based NetSuite sync writes **upstream** while the base field read **downstream**,
+41,381 of 72,134 prod orders across the 19 base-model tenants resolved no PO at all. The base
+`_purchaseOrders()` is now a **`COALESCE` of two scalar subqueries** — downstream first, upstream as
+the fallback — which fixes every upstream tenant at once and needed **no per-tenant override**.
+
+Branch state as verified **2026-08-26** (do not assume this is live):
+
+| Repo | Change | Where it lives |
+|---|---|---|
+| `_underscore` | the `COALESCE` fallback | commit `4579e0e7` on `TRUE-81284`, merged into **`_beta`**, `_sandbox-client`, `_sandbox-dev`. **Not on `_production`.** |
+| `dbchanges2` | `Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql` (the `CustomRecordFields` row for the schemas the 2026-08-11b rollout missed) | commit `0ca4012` on `TRUE-81284`, pushed. **Not on `_main` or `_beta`.** |
+
+Verified while applied: **zero existing values changed for any tenant** — the fallback only fills
+nulls — while coverage went NYCHH 64 → 819 of 819, Elite 57 → 288 of 288, Quad 475 → 1,456 of 1,463.
+The MySQL 8 plan stayed indexed (both subqueries `ref` on `idx_salesOrderId`, then `eq_ref` on the
+`PurchaseOrders` primary key) and `COALESCE` short-circuits, so the upstream subquery only runs when
+the downstream one is null.
+
+#### ⚠ Still open — which direction wins when an order has both
+
+Downstream-first shows the **vendor** PO, while the sales-orders **list** (whose table-view join
+reads upstream) shows the **customer** PO, so one order can display two different PO numbers in the
+list and in the modal. Orders carrying both are real and not rare: NYCHH 64, Elite 55, Quad 469.
+Downstream-first was chosen, then questioned in favour of treating the list as the source of truth;
+a per-tenant override on `_Model_Nychh_SalesOrder` preferring upstream was offered and **not built**.
+**Settle this before quoting either value as correct.**
 
 ### `poSelection` is a different thing
 The `poSelection` config on the `sales-order-record-actions` surface picks **which** linked PO the
@@ -74,14 +117,34 @@ the two — changing one does not move the other.
 - **Surface seed `id`s are deterministic; surface `uuid`s are not.** Seeds insert with `UUID()`, so
   the element uuid differs per environment. A uuid quoted in an older migration will **not** match
   the uuid in a live payload. Key surface updates on the literal `id` (here, `id = 7`).
-- **Downstream-only base implementation is a trap for upstream tenants.** On an upstream-only
-  tenant `_purchaseOrders` resolves cleanly (no `EV-8`) and returns `null` forever. See
+- **Downstream-only base implementation was a trap for upstream tenants.** On an upstream-only
+  tenant `_purchaseOrders` resolved cleanly (no `EV-8`) and returned `null` forever. Closed on
+  `_beta` by the `COALESCE` fallback above. See
   [SO↔PO bridge direction](./sales-order-purchase-order-bridge-direction.md) and
   [NYCHH PO Number](../../../clients/nychh/features/po-number-upstream-direction.md).
+- **A correct value here still may not reach the older TOGa Supply order-details modal.** That UI is
+  config-driven and declares the display row and the API field request **separately**: the
+  `DEFAULTFIELDS` and `QUAD` field sets ask for a `_purchaseOrders` row without listing
+  `_purchaseOrders` in `apiFields.fetchOrderDetails`, so it renders blank regardless of the SQL. See
+  [order-detail field config](../../toga2-supply/features/order-detail-field-config-and-customer-name.md).
+- **Fixing the SQL is not enough on a tenant whose schema lacks the metadata row.** No
+  `CustomRecordFields` row (`recordId` 14, field `_purchaseOrders`) means `EV-8` no matter what the
+  model returns, and the original per-client rollout **missed schemas** — prod 1 of 35, sandbox 7 of
+  36. See [calculated SQL fields](./calculated-sql-fields.md).
 - Dropping `isPersonaValue` is intentional; re-adding it will make the FE try to treat the string
   as a persona array.
 
 ## Change history
+- 2026-08-26 — Base `_purchaseOrders()` became a **`COALESCE`** of downstream-then-upstream, closing
+  the upstream-tenant gap for all base-model tenants with no per-tenant override (verified: no
+  existing value changed; NYCHH 64 → 819/819, Elite 57 → 288/288, Quad 475 → 1,456/1,463; plan stays
+  indexed). Recorded its branch state (`_beta`, **not** `_production`) and left the
+  **downstream-vs-upstream tie-break open** for orders carrying both (NYCHH 64, Elite 55, Quad 469),
+  where the modal and the list can disagree. **Corrected the tenant table**: Compass Canada is not on
+  the base implementation — it lives at `Model/Compass/Canada/` and inherits the Compass override, so
+  both Compass tenants move together and Compass Canada's upstream bridge is empty. Added the two
+  other independent causes of a blank PO (missing `CustomRecordFields` row → `EV-8`; the older supply
+  order-details field set never requesting the field). (bala)
 - 2026-08-25 — Repointed `SurfaceElements` id 7 to `_purchaseOrders` for all clients
   (`Core/2026-08-25a`, reverting `Core/2026-07-23a`) and made the FE adapter honour the surface
   `valueKey` instead of a hardcoded path; recorded the corrected per-tenant map, which supersedes

package/knowledge/2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md

@@ -6,17 +6,20 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-25
-owners: [apeterson]
+updated: 2026-08-26
+owners: [apeterson, bala]
 files:
   - _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
 related:
   - ./sales-order-po-number-sourcing.md
   - ./recursive-item-fulfillments.md
   - ./fulfillable-item-propagation.md
+  - ./netsuite-salesorder-address-phone-sync.md
   - ../../api2/features/v2-rest-query-contract.md
   - ../../../clients/nychh/features/po-number-upstream-direction.md
 ---
@@ -47,10 +50,45 @@ origin; the second is what was generated from it.
   - A multi-tier tenant (Compass USA) has **both**, chained SO→PO→SO→PO.
 - The only in-code statement of the distinction today is a docblock at
   `_underscore/Model/Client/ItemFulfillment.php:136-140`.
-- The base `_purchaseOrders` calculated field on `_Model_Client_SalesOrder` (line ~348) reads the
-  **downstream** table only. See
+- The base `_purchaseOrders` calculated field on `_Model_Client_SalesOrder` (line ~348) read the
+  **downstream** table only until 2026-08-25, when a **fallback to upstream** was added. See
   [sales-order PO Number sourcing](./sales-order-po-number-sourcing.md).
 
+### Two writers, one per direction — and the child key is what picks the table
+
+The two directions are not two views of one write; they are populated by **two different sync
+pipelines**, in **different frameworks**:
+
+| | UPSTREAM (`PurchaseOrders_SalesOrders`) | DOWNSTREAM (`SalesOrders_PurchaseOrders`) |
+|---|---|---|
+| Written by | **2.0** `_Trait_Netsuite_SalesOrder` (`_underscore/Trait/Netsuite/SalesOrder.php` ~:664-680 and ~:720) | **1.0** cron `App_Api_Toga2::syncPurchaseOrderFromNetsuite` (`library/app/api/toga2.php:2028`, posts the child key at :2504) |
+| api2 child key | `purchaseOrderSalesOrders` | `salesOrderPurchaseOrders` |
+| PO number stored | NetSuite `$nsOrder->otherRefNum` — the **customer's** PO (`EIT0011108`, `LOI-Woodhull`, `GAVELL/08252026`, Quad `4992713`) | the **vendor** PO — numeric NetSuite PO numbers (`168984`), Elite's `P100019` |
+
+**⚠ The child key is the only thing that decides which table you write, and getting it wrong is
+silent.** api2 treats `salesOrderPurchaseOrders` and `purchaseOrderSalesOrders` as two unrelated
+child collections, so a transposed key writes a perfectly valid row into the *other* direction and
+the reading side simply never sees it. No error, no warning. Read the key aloud, like the routes.
+
+Because **22 client `SalesOrder` models compose `_Trait_Netsuite_SalesOrder`**, every NetSuite-synced
+tenant writes **upstream** rows — which is why upstream-only tenants are the norm on that trait
+rather than the exception. (Grep the composition list before assuming a trait change is
+client-scoped; note the same grep also matches the `SalesOrderItem` / `SalesOrderStage` models, so
+count `SalesOrder.php` files only or you will report 66.)
+
+### How much downstream-only cost, measured on prod
+
+Because the base field read downstream only while the trait wrote upstream, **41,381 of 72,134**
+sales orders across the 19 base-model tenants returned no PO at all — only 30,753 resolved. Worst
+affected: NYCHH 64/822, Canon 594/6,290, GroWrk 1,226/12,793, S&P Global 971/9,468, Endeavor Health
+1,919/11,836. **An order can also carry both directions at once** (NYCHH 64, Elite 55, Quad 469),
+which is what makes the tie-break in
+[PO Number sourcing](./sales-order-po-number-sourcing.md) a real decision rather than a formality.
+
+All **35** prod client schemas contain all four tables (`SalesOrders`, `PurchaseOrders`, both
+bridges), verified via `information_schema` — so reading either direction is structurally safe
+everywhere. Present is not populated.
+
 ## Gotchas
 
 - **An empty array is the symptom.** `200` / `totalRecordCount 0` with **no** `EZ-*` or `EV-*`
@@ -62,11 +100,38 @@ origin; the second is what was generated from it.
 - **The routes are near-homographs.** `sales-order-purchase-orders` vs
   `purchase-order-sales-orders`. Read them aloud before wiring a front-end call.
 - **Downstream-only assumptions are baked into shared code.** Any tenant whose POs are purely
-  upstream (verified: NYCHH; suspected: Compass Canada, which has no `Model/Compasscanada/`
-  overrides at all) silently gets `null`/empty from the shared downstream-reading helpers rather
-  than an error. Upstream-only tenants need an explicit upstream counterpart field.
+  upstream (verified: NYCHH) silently gets `null`/empty from the shared downstream-reading helpers
+  rather than an error.
+- **⚠ Compass Canada is NOT upstream-only, and it DOES have model overrides** — corrected
+  2026-08-26. The earlier "no `Model/Compasscanada/` directory" reading looked in the wrong place:
+  the folder is **`_underscore/Model/Compass/Canada/`**, and
+  `_Model_Compass_Canada_SalesOrder extends _Model_Compass_SalesOrder`, so Compass Canada inherits
+  **Compass's** `_purchaseOrders` override, not the base one. Its **upstream bridge is completely
+  empty (0 rows)** while 735 of 788 orders resolve a PO downstream. When checking whether a tenant
+  has overrides, search for the class name (`grep -rn "class _Model_.*_SalesOrder extends"`) rather
+  than guessing a directory — Compass's tenants nest one level deeper than everyone else's.
+- **⚠ Do NOT paper over the direction with an `ojoin` on a shared single-record fetch.** It is
+  tempting because it works in one place: the TOGa Supply NYCHH orders **list** joins the upstream
+  bridge and is correct — but only because NYCHH's upstream bridge happens to be **1:1** (823 rows /
+  823 distinct sales orders, max 1 PO per SO). The same join in the shared
+  `fetchOrdersDetails` (`toga2-supply/src/pages/Orders/api/OrdersApi.ts:397`) breaks three tenants:
+  **Compass** has up to **6,440** downstream POs on one sales order (row multiplication on a
+  single-record fetch), **Compass Canada's upstream bridge is empty** (735 of 788 would drop to
+  **zero**), and **Prudential** has only **1,868 of 26,843** orders upstream (92% populated would
+  become 7%). A scalar `GROUP_CONCAT` calculated field is the right mechanism precisely because it
+  collapses many POs without multiplying rows.
 
 ## Change history
+- 2026-08-26 — Added the **write** side: the two directions are populated by two different
+  pipelines (2.0 `_Trait_Netsuite_SalesOrder` writes **upstream** customer POs from `otherRefNum`;
+  the 1.0 `syncPurchaseOrderFromNetsuite` cron writes **downstream** vendor POs), and the api2 child
+  key (`purchaseOrderSalesOrders` vs `salesOrderPurchaseOrders`) is the only thing selecting the
+  table — a transposed key writes the wrong direction silently. Quantified the downstream-only cost
+  on prod (41,381 of 72,134 orders returned no PO across the 19 base-model tenants) and noted
+  tenants carrying both directions. **Corrected the Compass Canada claim**: it has overrides at
+  `Model/Compass/Canada/` and inherits the Compass `_purchaseOrders` override, and its upstream
+  bridge is empty — it is downstream-only, not upstream-only. Added the "do not fix this with an
+  `ojoin`" gotcha with the Compass / Compass Canada / Prudential regressions it would cause. (bala)
 - 2026-08-25 — Documented the two-direction bridge after an NYCHH "empty array" debug that was
   purely a wrong-direction query; recorded route/model/record-id mapping and the empty-vs-EZ
   diagnostic signature (apeterson)

package/knowledge/2.0/apps/toga2-supply/features/order-detail-field-config-and-customer-name.md

@@ -18,7 +18,7 @@ related:
   - ../../../../clients/elite/features/supply2-scope.md
   - ../workflows/client-host-scoping.md
   - ../architecture.md
-  - ../../_underscore/features/purchase-order-sales-order-bridges.md
+  - ../../_underscore/features/sales-order-purchase-order-bridge-direction.md
 ---
 
 ## Summary
@@ -109,7 +109,7 @@ As of 2026-08-26 that still reports `1` for `DEFAULTFIELDS.json` and the three `
 fix was drafted this session but is not present on any branch or stash.** The backend half (the
 `_purchaseOrders` calculated field reading the wrong bridge table) is a separate, independent cause
 of the same blank row; see
-[PO-to-SO bridge tables](../../_underscore/features/purchase-order-sales-order-bridges.md).
+[PO-to-SO bridge tables](../../_underscore/features/sales-order-purchase-order-bridge-direction.md).
 
 ### Which field set a host gets
 
@@ -164,7 +164,7 @@ requires **both** changes, not either one:
   covers COMPASS / COMPASSCANADA / QUAD (+ an ELITE early return), so **every other host falls
   through to `DEFAULTFIELDS`** — a default-set gap is a platform-wide gap. The four-file fix was
   drafted but is **not on any branch**; the backend half is a separate cause, see
-  [PO-to-SO bridge tables](../../_underscore/features/purchase-order-sales-order-bridges.md). (bala)
+  [PO-to-SO bridge tables](../../_underscore/features/sales-order-purchase-order-bridge-direction.md). (bala)
 - 2026-08-18 — First capture. Documented that the order-details Customer name is **hardcoded in the
   frontend**, not read from the database: every host's config uses
   `valueKey: "orderBoxDetails.customer.name"`, `orderBoxDetails` exists nowhere in the codebase or

package/knowledge/clients/nychh/INDEX.md

@@ -2,5 +2,5 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
-| [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, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts, dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.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 |
 | [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 |

package/knowledge/clients/nychh/features/po-number-upstream-direction.md

@@ -6,12 +6,14 @@ project: _Underscore
 client: nychh
 type: client-feature
 status: active
-updated: 2026-08-25
-owners: [apeterson]
+updated: 2026-08-26
+owners: [apeterson, bala]
 files:
   - _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
 related:
   - ../../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md
   - ../../../2.0/apps/_underscore/features/sales-order-po-number-sourcing.md
@@ -22,7 +24,13 @@ related:
 
 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 `purchase-order-sales-orders`,
-record 276). They have **no** downstream `SalesOrders_PurchaseOrders` rows.
+record 276). Their POs are the customer's own numbers — `EIT0011108`, `COR0015555`,
+`LOI-Woodhull` — written from NetSuite `otherRefNum` by `_Trait_Netsuite_SalesOrder`.
+
+**Refinement (prod, 2026-08-26): "no downstream rows" holds for the vast majority but not all.** Of
+822 NYCHH sales orders, **64 carry a PO in BOTH directions**, which is exactly the set where the
+list and the modal can disagree — see the open tie-break below. On prod the downstream-only base
+field resolved a PO on only **64 of 822** orders.
 
 This produced a symptom that looked like a bug and was not: the sales-order modal's PO Number came
 back as an empty array while the sales-orders **list** column showed a PO number for the same
@@ -44,16 +52,35 @@ the **upstream** table.
 
 ## Gotchas
 
-- 🚨 **Open consequence.** The shared `_purchaseOrders` calculated field reads the **downstream**
-  table (`_underscore/Model/Client/SalesOrder.php:348`). Now that the modal's PO Number binds to
-  `_purchaseOrders`, NYCHH resolves it without an `EV-8` but gets **`null` forever**. NYCHH needs an
-  **upstream counterpart** — either an upstream-aware override of `_purchaseOrders` for this tenant
-  or an upstream variant field. **No tenant precedent exists for upstream-only:** Compass USA reads
-  both, Quad and Compass Canada are downstream-only.
+- ✅ **The open consequence is addressed on `_beta` — and NOT with a per-tenant override.** The
+  shared `_purchaseOrders` field read the **downstream** table only
+  (`_underscore/Model/Client/SalesOrder.php:349`), so once the modal bound to `_purchaseOrders`
+  NYCHH resolved it without an `EV-8` and got `null`. Rather than a NYCHH-specific field, the
+  **base** field became a `COALESCE` of downstream-then-upstream, which fixed every upstream tenant
+  at once: NYCHH went from 64 to **819 of 819** orders resolving a PO, with **no existing value
+  changed** for any tenant. It sits on `_beta` / the sandbox branches, **not `_production`** — see
+  [PO Number sourcing](../../../2.0/apps/_underscore/features/sales-order-po-number-sourcing.md) for
+  the exact commits. NYCHH is also not the only upstream tenant: all 22 clients on
+  `_Trait_Netsuite_SalesOrder` write upstream.
+- 🚨 **Still open for NYCHH specifically: the 64 both-direction orders.** Downstream-first makes the
+  modal show the **vendor** PO while the list keeps showing the **customer** PO. A
+  `_Model_Nychh_SalesOrder` override preferring upstream was offered and not built. Decide which one
+  NYCHH should see before treating either surface as authoritative.
+- **The NYCHH orders list is not a template.** Its table-view join through the upstream bridge is
+  safe **only** because NYCHH's upstream bridge is coincidentally 1:1 (823 rows / 823 distinct sales
+  orders). Copying that join into a shared single-record fetch breaks Compass (up to 6,440 POs on one
+  order), Compass Canada (empty upstream bridge) and Prudential (1,868 of 26,843 upstream).
 - Do not "fix" this by adding downstream rows. The direction is correct for NYCHH's business model;
-  the shared field is what is incomplete.
+  the shared field is what was incomplete.
 
 ## Change history
+- 2026-08-26 — Closed the open `_purchaseOrders` gap: fixed in the **base** field as a
+  downstream-then-upstream `COALESCE` (not a NYCHH override), taking NYCHH from 64 to **819 of 819**
+  orders with a PO and changing no existing value; currently on `_beta`, not `_production`. Refined
+  "no downstream rows" — **64 of 822** NYCHH orders have both directions, which is the remaining open
+  question (modal would show the vendor PO, the list shows the customer PO). Recorded that the NYCHH
+  orders-list upstream join is safe only because their upstream bridge is 1:1 and must not be copied
+  into a shared fetch. (bala)
 - 2026-08-25 — Diagnosed the empty-array PO Number as a wrong-direction query (upstream data,
   downstream route); ruled out ACL and migrations; recorded the still-open `_purchaseOrders`
   downstream-only gap for this tenant (apeterson)

package/package.json

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