toga-ai 1.0.651 → 1.0.653

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

@@ -4,13 +4,13 @@
 |-----|---------|-------|
 | [Proposed — git-sourced base+overlay JSON authoring for the Surface layer](architecture/surface-authoring-proposal.md) | A **proposal / handoff recommendation** (not implemented) that the Surface layer's *authoring* model move off hand-authored SQL against the `SurfaceOverrides` E | _underscore/Model/Core/Surface.php, _underscore/Model/Client/SurfaceOverride.php |
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
-| [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, _underscore/Model/Client/TrackingNumber.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission.sql, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql |
+| [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, _underscore/Model/Client/TrackingNumber.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission.sql, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql, dbchanges2/Client_Quad/2026-08-24 - Quad Multi Currency Item Pricing.sql |
 | [Address Uniqueness Normalization (unit identifier + 5-digit ZIP comparison)](features/address-uniqueness-normalization.md) | When a business rule says *"only one X per physical address"*, comparing address rows field-for-field does **not** work: the same dwelling is spelled many diffe | _underscore/Model/Rate/Entitlement.php |
 | [Address Validation (carrier waterfall + validateAddress scripted endpoint)](features/address-validation.md) | `_Model_Client_Address::validateAddress` verifies a US address against a **carrier waterfall (USPS → FedEx → UPS)** and returns a single canonical, carrier-norm | _underscore/Model/Client/Address.php, _underscore/Component/Library/Carriers/Usps/Usps.php |
 | [_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, dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.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/SalesOrder.php, _underscore/Model/Client/ServiceRequest.php, _underscore/Model/Elite/SalesOrder.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 |
@@ -32,13 +32,13 @@
 | [_Model::save() vs raw _Query — no atomic conditional update](features/model-save-vs-query-atomic-update.md) | `_Model::save()` is a plain load-then-write ORM primitive and **cannot express an atomic conditional update** (an optimistic-concurrency / row-claim guard such | _underscore/Model.php, _underscore/Query.php, _underscore/Model/Rate/Subscription.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php, _underscore/Trait/Netsuite/SalesOrder.php, worker2/Worker/Netsuite/SalesOrder.php, worker2/Component/Forecast/SaleImport/SaleImport.php, worker2/Worker/Netsuite/Opportunity.php |
 | [NetSuite Sales Order sync — ship-to address, phone, and PO reference sourcing](features/netsuite-salesorder-address-phone-sync.md) | `_Trait_Netsuite_SalesOrder` is the **shared** sales-order importer composed into **22 client models** (every client on the dbchanges2 `netsuite` module). | _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Model.php, dbchanges2/_modules/netsuite/2026-08-10a - AddressPhoneNumberApiRoleAcl.sql |
-| [Legacy page meta (Page::meta) & context-scoped ClientRecordFieldSettings](features/page-meta-context-field-settings.md) | `_Model_Core_Page::meta()` is the **legacy** page-meta resolver behind `GET /pages/meta?slug=<slug>` — still the live path for `toga2-supply` and other pre-Surf | _underscore/Model/Core/Page.php, _underscore/Model/Client/TableView.php, toga2-supply/src/components/ui/Tables/PrimaryTable/PrimaryTable.tsx |
+| [Legacy page meta (Page::meta) & context-scoped ClientRecordFieldSettings](features/page-meta-context-field-settings.md) | `_Model_Core_Page::meta()` is the **legacy** page-meta resolver behind `GET /pages/meta?slug=<slug>` — still the live path for `toga2-supply` and other pre-Surf | _underscore/Model/Core/Page.php, _underscore/Model/Client/TableView.php, toga2-supply/src/components/ui/Tables/PrimaryTable/PrimaryTable.tsx, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/formatTableData.tsx |
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/Model.php, _underscore/Query.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php, api2/Controller/Index.php |
 | [Persona Name Translation (PersonaTranslations sidecar)](features/persona-name-translation.md) | Serves Persona **names** in multiple languages by adding a per-language **sidecar** table `PersonaTranslations`, reusing the platform's existing metadata-driven | _underscore/Model/Client/PersonaTranslation.php, dbchanges2/Client/2026-07-22b - PersonaTranslations.sql, dbchanges2/Core/2026-07-22a - PersonaTranslationsRecord.sql, dbchanges2/Client/2026-07-22c - PersonaTranslationsAcl.sql, dbchanges2/Client_CompassCanada/2026-07-22 - PersonaTranslationsFrench.sql, toga2-commerce/src/pages/Account/view/MySettingsView.tsx |
 | [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/acl-permission-chain.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-18
+updated: 2026-08-26
 owners: ["jcardinal", "mhammontree", "tcox", "bala"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -16,6 +16,7 @@ files:
   - dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql
   - dbchanges2/Client/2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission.sql
   - dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql
+  - dbchanges2/Client_Quad/2026-08-24 - Quad Multi Currency Item Pricing.sql
 ---
 
 ## Summary
@@ -129,6 +130,16 @@ nothing:
 | **Standard** (e.g. `serviceAddressId`) | `Core.RecordFields` | **`AclFieldPermissions`** | `Core.RecordFields` id |
 | **Custom** (`c_` prefix) | `CustomRecordFields` | **`AclCustomFieldPermissions`** | `CustomRecordFields` id |
 
+**A `CustomRecordFields` row is not always a `c_` field, and a presentation-only override needs NO
+grant.** A client may register a `CustomRecordFields` row that deliberately **reuses an existing
+Core field's name** purely to override that field's `type` for one client (the only client-scoped
+way to change a table-view column's rendering type — see
+[TableView field/column metadata](../../api2/features/tableview-field-metadata.md#per-client-type-override)).
+In that case authorization still resolves through the Core field's `AclFieldPermissions` row for
+that name, so **do not** add an `AclCustomFieldPermissions` row: it is unnecessary, and it would let
+the column keep working after the Core grant is revoked. Verified on Quad's `_unitPrice` / `_unitCost`
+(2026-08-26).
+
 **Promoting a custom field to a standard field moves its grant to the other table.** When
 `c_serviceAddressId` was promoted to the standard `serviceAddressId` (Rate WH guard, TRUE-79533),
 its `CustomRecordFields` row was deleted, so the pending `AclCustomFieldPermissions` grant
@@ -204,6 +215,39 @@ then checks the caller's roles against `AclRecordPermissions` (→ `EZ-1` if no
 readable/writable fields from `AclFieldPermissions`. `_Model_Core_Page::meta()` reads the same
 tables to return per-page ACL to the frontend.
 
+## Navigation / action flags (`Core.AclActions` + `AclActionPermissions`) — a THIRD gate
+
+A UI control that is not a record CRUD operation and not a scripted API — a nav item, an "Add" or
+"Edit" button in `toga2-supply` — is gated by an **action flag** that the frontend reads out of the
+page meta as `acl['<page-route>']['<action-slug>']`. Two tables:
+
+- **`Core.AclActions`** — the flag itself: `recordId` + `slug`. Example: on record **19**
+  (`VendorItems`), id **5** = `navigation-vendor-items` (can the page be reached) and id **7** =
+  `navigation-edit-on-vendor-items` (can rows be added/edited).
+- **`Client_*.AclActionPermissions`** — `(aclActionId, roleId)`: the grant.
+
+`_Model_Core_Page::meta()` (~L1285–1302) **initialises every action flag on the page to `false`** and
+flips it to `true` only when an `AclActionPermissions` row matches one of the caller's roles. So a
+missing row is not an error anywhere — the button is simply not rendered.
+
+**⚠ This gate is INDEPENDENT of the CRUD chain, which is what makes it hard to diagnose.** The page
+meta can report `_CREATE` / `_UPDATE` / `_DELETE` `true` (because `AclRecordPermissions` grants them)
+while the button that would invoke them is hidden, so every permission check you run says
+"permissions are fine" and it reads as a frontend bug.
+
+**Recipe when a control is missing for one client:** find the exact flag slug the component reads
+(both the Add and the Edit control commonly read the *same* flag), then diff
+`AclActionPermissions` against a client where the control works, and grant the missing
+`(aclActionId, roleId)` in a `dbchanges2` migration.
+
+Worked example (Quad, 2026-08-26): the vendor-items **Add and Edit buttons both** read
+`acl['vendor-items']['navigation-edit-on-vendor-items']` (AclActions id 7). `Client_Quad` had a row
+for id 5 only, so the page was reachable but button-less, even though record 19 already granted role
+1 — held by every Quad user — full CRUD. Prod comparison: Compass grants 5 → roles 9,11 and 7 → role
+16; Compass Canada grants 5 and 7 both → role 10. Quad followed Compass Canada and granted id 7 to
+role 7 (Global Admin). Because this is only a UI gate, the fix is purely additive and cannot widen
+data access.
+
 ## Record-script dispatch grant (`AclRecordScripts`) — a separate gate
 
 A **scripted API** (Record Script) has its own ACL gate, **distinct from the four-table record-CRUD
@@ -359,6 +403,16 @@ hardcoded `Core.RecordFields` id literals instead of a subselect.
       and every repo is on the **same branch** so the generated model matches the DB.
 
 ## Change history
+- 2026-08-26 - Added the **action-flag gate** (`Core.AclActions` + `Client_*.AclActionPermissions`),
+  a third gate alongside record CRUD and record scripts: `Page.php` (~L1285-1302) defaults every
+  action flag to `false` and only a matching `AclActionPermissions` row flips it true, so a missing
+  row silently hides a nav item or an Add/Edit button while the page meta still reports
+  `_CREATE/_UPDATE/_DELETE` true. Worked example: Quad's vendor-items Add **and** Edit both read
+  `navigation-edit-on-vendor-items` (AclActions id 7 on record 19); Quad had id 5 only, fixed by
+  granting id 7 to role 7 following Compass Canada. Also noted that a `CustomRecordFields` row which
+  reuses a Core field's name to override its **type** for one client must **not** get an
+  `AclCustomFieldPermissions` row - the Core grant governs, and an extra row would survive a revoke.
+  (bala)
 - 2026-08-18 - Caveated "explicitly seeded and identical in every environment": true for
   established `Core.RecordFields` rows, but the **next free id differs per environment** (a new
   field took 2483 in prod, 2766 in dev-sandbox), so a newly created row may need a per-environment

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

@@ -6,20 +6,24 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-18
+updated: 2026-08-26
 owners: [snaredla, jcardinal, bala]
 files:
   - _underscore/Model.php
   - _underscore/Model/Client/SalesOrder.php
   - _underscore/Model/Client/ServiceRequest.php
   - _underscore/Model/Elite/SalesOrder.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
 related:
   - ../architecture.md
   - ./acl-permission-chain.md
   - ../../api2/features/v2-api-error-codes.md
   - ./model-magic-field-access.md
   - ./model-save-parent-cascade-stored-field-deadlock.md
+  - ./sales-order-purchase-order-bridge-direction.md
 ---
 
 ## Summary
@@ -56,6 +60,35 @@ fallback — `_serialNumbers` the property requires `_serialNumbers()` the metho
 Options: `FIELDOPT_SQL_TYPE` (defaults to `FIELD_CHAR`) and `FIELDOPT_SQL_STORED` (default `false`,
 recalculated per query; `true` persists to a real column on save).
 
+### ⚠ `FIELDOPT_SQL_TYPE` casts the returned VALUE — a TEXT-returning field must be plain `FIELD_SQL`
+
+`FIELDOPT_SQL_TYPE` is **not** only a hint for ordering/pagination cursors: it rewrites the value
+the API returns. `getSqlFieldValue()` (`Model.php` ~L509–520) reads the option off the field
+definition and pipes the fetched value through `formatValueForField()` (~L728), whose `switch`
+**casts**:
+
+| `FIELDOPT_SQL_TYPE` | what happens to the value |
+|---|---|
+| `FIELD_DECIMAL` | `(float) $value` |
+| `FIELD_INTEGER` / `FIELD_FOREIGNKEY` / `FIELD_PRIMARYKEY` | `(int) $value` |
+| `FIELD_BOOLEAN` | `null` or a real bool |
+| **omitted** (defaults to `FIELD_CHAR`) | **nothing — there is no `case self::FIELD_CHAR`, so the value passes through untouched** |
+
+So a calculated field that returns text but is declared
+`[self::FIELD_SQL, self::FIELDOPT_SQL_TYPE => self::FIELD_DECIMAL]` is **silently zeroed**:
+`(float) 'PLN 5295.00'` is `0`. The symptom — api2 returning `_unitPrice: 0` and the grid rendering
+an em dash — points nowhere near the declaration, and the SQL is right there returning the correct
+string when run by hand.
+
+**Rule: if the expression can return text — a formatted amount, a `GROUP_CONCAT`, a status word —
+declare the field as plain `self::FIELD_SQL` with NO `FIELDOPT_SQL_TYPE`.** `_priceType` is the
+in-tree precedent for a text-returning calculated field. Only add the option when the expression
+really does return a number of that type.
+
+Verified 2026-08-26 on `_Model_Quad_Item::_unitPrice`, which returns a `GROUP_CONCAT` of
+`'CODE amount'` pairs across a Quad item's currencies (see
+[Quad multi-currency item pricing](../../../../clients/quad/features/multi-currency-item-pricing.md)).
+
 ## Exposing a calculated field to the API - a client `CustomRecordFields` row is enough
 
 **Declaring the field on the model does not make it requestable.** A client whose DB has no
@@ -88,6 +121,21 @@ first pass and nothing on the second; against `Client_Compass` it inserted nothi
 id 77 and its role 1/3/4 grants untouched. Prudential gains the field across **26,280**
 `SalesOrders_PurchaseOrders` rows.
 
+**⚠ Idempotent is not the same as applied — audit every schema afterwards.** A `Client/`-scoped
+migration is run per client DB by hand, so a single missed schema leaves that client with `EV-8`
+forever and nobody notices until a user reports a blank field. Re-auditing `_purchaseOrders` two
+weeks after the 2026-08-11b rollout found it **missing on `Client_Imhouston` (1 of 35) on prod and
+on 7 of 36 client-sandbox schemas** (Aig, Browardsheriff, Canon, GroWrk, Imhouston, Masonite,
+Trividiahelth). The re-runnable follow-up is
+`Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql`. Query
+`information_schema` / `CustomRecordFields` across every schema rather than trusting that the
+original change-set was run everywhere. Watch for near-duplicate schemas while you audit —
+`Client_Trividiahelth` is a **misspelled duplicate** that exists only on client-sandbox.
+
+The ACL convention for these rows: grants go to the **`Base` and `API` roles only, resolved BY
+NAME**. Most other `SalesOrders` custom fields carry `Base` alone, so `Base + API` is already the
+generous end; `Developer` and `Public` get no ACL row for any field.
+
 ## Gotchas / known issues
 
 - **⚠ Never add a parameter TYPE to an override whose parent declares the parameter untyped - it
@@ -125,7 +173,22 @@ id 77 and its role 1/3/4 grants untouched. Prudential gains the field across **2
   [save-cascade stored-field deadlocks](./model-save-parent-cascade-stored-field-deadlock.md).
 
 ## Change history
-
+- 2026-08-26 - **`FIELDOPT_SQL_TYPE` casts the returned VALUE, not just sort/pagination cursors.**
+  `getSqlFieldValue()` (`Model.php` ~L509-520) hands the fetched value to `formatValueForField()`
+  (~L728), which `(float)`s a `FIELD_DECIMAL` field - so a text-returning calculated field declared
+  `FIELDOPT_SQL_TYPE => FIELD_DECIMAL` is silently zeroed (`(float) 'PLN 5295.00'` = 0, seen as
+  `_unitPrice: 0` + an em dash in the grid). A text-returning field must be plain `self::FIELD_SQL`:
+  the option defaults to `FIELD_CHAR`, which has **no case** in the switch, so the value passes
+  through. `_priceType` is the precedent. Verified on `_Model_Quad_Item::_unitPrice`. (bala)
+
+- 2026-08-26 - Added the **audit-after-rollout** rule: an idempotent `Client/`-scoped migration is
+  still run per schema by hand, and re-auditing `_purchaseOrders` found it missing on
+  `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](./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
   `CustomRecordFields` row is sufficient and **no `Core.RecordFields` row is needed** (Compass's
   `_purchaseOrders` = id 77, with `_totalLease` 81 / `_trackingNumbers` 83, has no Core row and

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

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-11
-owners: ["mhammontree"]
+updated: 2026-08-26
+owners: ["mhammontree", "bala"]
 files:
   - _underscore/Trait/Netsuite/SalesOrder.php
   - _underscore/Model.php
@@ -16,6 +16,7 @@ related:
   - acl-permission-chain.md
   - address-uniqueness-normalization.md
   - carrier-shipping-labels.md
+  - sales-order-purchase-order-bridge-direction.md
   - ../../toga2-supply/features/fulfill-and-ship.md
   - ../../api2/features/record-scripts.md
 ---
@@ -40,6 +41,17 @@ 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 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
 
 1. **Normalise a phone with `_String::cleanPhoneNumber()` on the way INTO the payload.**
@@ -90,6 +102,12 @@ 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 **upstream** bridge
+  (`PurchaseOrders_SalesOrders`, customer PO), while the shared `SalesOrders._purchaseOrders`
+  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 [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/page-meta-context-field-settings.md

@@ -6,12 +6,13 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-18
+updated: 2026-08-26
 owners: [tcox, bala]
 files:
   - _underscore/Model/Core/Page.php
   - _underscore/Model/Client/TableView.php
   - toga2-supply/src/components/ui/Tables/PrimaryTable/PrimaryTable.tsx
+  - toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/formatTableData.tsx
 related:
   - surface-resolver.md
   - ../../api2/features/tableview-field-metadata.md
@@ -36,6 +37,43 @@ bug that takes down *unrelated* pages for any client that uses the feature.
 Example (Elite): row id 1 relabels field **58** to **"Total"** in the context of field **190**
 (`ServiceRequests.id`) — authored for the `service-requests` view.
 
+## Column TYPE and column LABEL come from TWO DIFFERENT endpoints
+
+Before chasing a grid column's appearance, know which endpoint owns the thing you want to change —
+they never influence each other:
+
+| What you see | Source endpoint | Payload path | Consumer (`toga2-supply`) |
+|---|---|---|---|
+| the column's **type / formatting** (currency icon, number/decimal rendering) | `/table-views/meta` | `table.fields[].type` | `generateDynamicConfig` → `formatTableData.tsx` |
+| the column's **header text** | `/pages/meta` | `settings.fields[<record route>][<field>]['label-singular']` | `PrimaryTable.convertColumnTitles` |
+
+So a currency/dollar icon on a column is a **type** problem (fix the field's `type` — Core
+`RecordFields`, or a client-scoped override, see
+[TableView field/column metadata](../../api2/features/tableview-field-metadata.md#per-client-type-override)),
+and a wrong header is a **settings-row** problem. Adding a label row will never change the icon,
+and retyping the field will never change the header.
+
+### ⚠ A CUSTOM record field's label row is UNREACHABLE from the grid header
+
+`Page.php` emits `ClientCustomRecordFieldSettings` in its own block (~L900–935) and keys it by a
+record route resolved through `$lookupRecordIdFromCustomRecordFieldId` →
+`$lookupRecordFromRecordId[...]->route`. In practice, for a column pointed at a
+`CustomRecordFields` row, that resolves to an **empty** record-route key — the row lands at
+`settings.fields[""][<field>][…]`, a bucket `convertColumnTitles` never reads. **A
+`ClientCustomRecordFieldSettings` `label-singular` row for a custom column is therefore dead
+metadata**, and no amount of adding/correcting those rows will move the header. (Measured
+2026-08-26: two hours lost adding label rows that could never be read.)
+
+Where the label must come from instead, for such a column:
+
+- **`Core.DefaultRecordFieldSettings`** on the underlying **Core** `RecordField`, or
+- **`ClientRecordFieldSettings`** when the column points at a real `RecordField`,
+
+in both cases with **`contextRecordFieldId` and `contextCustomRecordFieldId` NULL** — the
+context-free branch at `Page.php` ~L831 is what writes
+`settings.fields[record][field][setting]`, the exact path the header reads. This is the same
+"keep label rows plain" conclusion as the correction below, reached from the other direction.
+
 ## Why this matters: table-view **column headers** for joined columns need context rows
 
 This is the mechanism behind "why is my column header a camelCase slug?" — and the answer is
@@ -143,6 +181,16 @@ data change, is what makes it fatal.
   customization. The guard belongs in the framework.
 
 ## Change history
+- 2026-08-26 - Documented that a grid column's **type** and its **header label** come from two
+  different endpoints: type/formatting (the currency icon) from `/table-views/meta`
+  `table.fields[].type` via `generateDynamicConfig` → `formatTableData`, header text from
+  `/pages/meta` `settings.fields[<record route>][<field>]['label-singular']` via
+  `PrimaryTable.convertColumnTitles`. Added the trap that a **custom** record field's settings rows
+  are emitted in `Page.php`'s separate `ClientCustomRecordFieldSettings` block (~L900-935) under an
+  **empty** record-route key, so a `ClientCustomRecordFieldSettings` label row for a custom column is
+  never read - the label must come from `Core.DefaultRecordFieldSettings` on the underlying Core
+  RecordField (or `ClientRecordFieldSettings` when the column points at a real RecordField), with
+  both context columns NULL. (bala)
 - 2026-08-18 - **Corrected the "joined columns need a context row" guidance.** `PrimaryTable.tsx`
   takes the context branch whenever `contextField` is set and **never falls back** to the plain
   lookup, so a context row whose context does not resolve in the meta leaves the header as its raw

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)