toga-ai 1.0.649 → 1.0.650

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

@@ -37,6 +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 |
 | [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/sales-order-po-number-sourcing.md

@@ -0,0 +1,88 @@
+---
+title: "Sales-order \"PO Number\" sourcing — one surface element, `_purchaseOrders`, tenant SQL underneath"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-08-25
+owners: [apeterson]
+files:
+  - _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
+related:
+  - ./sales-order-purchase-order-bridge-direction.md
+  - ./calculated-sql-fields.md
+  - ./surface-resolver.md
+  - ../../toga25-supply/features/surface-frontend.md
+  - ../../dbchanges2/features/surface-layer-schema.md
+---
+
+## Summary
+
+The sales-order modal's **PO Number** field is **not** tenant-split at the display layer. As of
+2026-08-25 every tenant renders it the same way:
+
+```
+Core.SurfaceElements id 7  (Order Details "PO Number", messages.label = salesOrder.field.poNumber)
+  → config.valueKey = "_purchaseOrders"
+  → FE adapter toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts
+  → renders the order's `_purchaseOrders` calculated field (comma-joined string)
+```
+
+**All tenant variation lives underneath, in the SQL behind `_purchaseOrders`** — not in the
+surface, not in the front end. This supersedes the earlier (TRUE-81190) understanding that the
+*display path* itself was tenant-split.
+
+## How it works
+
+### The display binding
+`SurfaceElements` id 7 carries `config = {"valueKey": "_purchaseOrders"}`. `isPersonaValue` is
+deliberately **not** set: the value is a scalar comma-joined string, not a persona array.
+
+`surfaceBundleToTenantFields.ts` exposes `PO_NUMBER_VALUE_KEY` and resolves it against the order
+via `resolvePathInsensitive(valueKey)`, normalising an empty string to an em-dash.
+
+### The tenant layer (`_purchaseOrders`)
+| 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`) |
+
+### `poSelection` is a different thing
+The `poSelection` config on the `sales-order-record-actions` surface picks **which** linked PO the
+*editable* flow treats as primary (Enter-PO modal prefill, `approveButtonRule`, completion state).
+Core default is `"first"`; Quad is overridden to `"mostRecent"` by
+`Client_Quad/2026-08-19a`. It reads the **downstream join**, not `_purchaseOrders`. Do not conflate
+the two — changing one does not move the other.
+
+## Gotchas
+
+- **A surface-config change is only real if the FE actually honours the binding.** Before
+  2026-08-25 the FE constant *matched* the surface's `valueKey` and then **discarded** it,
+  substituting a hardcoded field path. The config was read and thrown away — so shipping the
+  migration alone would have silently done nothing. Whenever you repoint a `valueKey`, grep the FE
+  for the old literal and confirm it resolves *through* the config, not around it.
+- **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
+  [SO↔PO bridge direction](./sales-order-purchase-order-bridge-direction.md) and
+  [NYCHH PO Number](../../../clients/nychh/features/po-number-upstream-direction.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-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
+  the tenant-split display understanding (apeterson)

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

@@ -0,0 +1,72 @@
+---
+title: "SO↔PO bridge tables are TWO tables in OPPOSITE directions (upstream vs downstream)"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-08-25
+owners: [apeterson]
+files:
+  - _underscore/Model/Client/PurchaseOrders/SalesOrder.php
+  - _underscore/Model/Client/SalesOrders/PurchaseOrder.php
+  - _underscore/Model/Client/ItemFulfillment.php
+  - _underscore/Model/Client/SalesOrder.php
+related:
+  - ./sales-order-po-number-sourcing.md
+  - ./recursive-item-fulfillments.md
+  - ./fulfillable-item-propagation.md
+  - ../../api2/features/v2-rest-query-contract.md
+  - ../../../clients/nychh/features/po-number-upstream-direction.md
+---
+
+## Summary
+
+There are **two** bridge tables linking sales orders and purchase orders, and they mean
+**opposite things**. Both names are legal under the bridge-table naming convention (sibling
+tables may be named in either order), and the two API routes differ only in word order — so
+**nothing at the API surface tells you which direction you are querying**. Querying the wrong
+one returns `200` with an empty array, which reads like a permission or data bug and is not.
+
+| Table | Direction | Meaning | Model | API route | `Core.Records` id |
+|---|---|---|---|---|---|
+| `PurchaseOrders_SalesOrders` | **UPSTREAM** | a sales order created **FROM** a purchase order — the *customer's* PO | `_Model_Client_PurchaseOrders_SalesOrder` | `purchase-order-sales-orders` | 276 |
+| `SalesOrders_PurchaseOrders` | **DOWNSTREAM** | a purchase order created **FROM** a sales order — a *vendor* PO | `_Model_Client_SalesOrders_PurchaseOrder` | `sales-order-purchase-orders` | 275 |
+
+Read the name as **"`<source>`\_`<thing created from it>`"**. The *first* table name is the
+origin; the second is what was generated from it.
+
+## How it works
+
+- Both `Records` rows are `aclDatabase = CLIENT`, `childPolicy = MATCH_UPSERT`, so both are
+  per-tenant data and both accept nested writes that match-or-create the link row.
+- Which direction a tenant actually populates depends on how their orders enter the platform:
+  - Customer sends TOGa a PO which becomes a sales order → **upstream** rows.
+  - TOGa raises vendor POs to fulfil a sales order → **downstream** rows.
+  - 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
+  [sales-order PO Number sourcing](./sales-order-po-number-sourcing.md).
+
+## Gotchas
+
+- **An empty array is the symptom.** `200` / `totalRecordCount 0` with **no** `EZ-*` or `EV-*`
+  message is the signature of *"the join matched nothing"* — i.e. wrong direction — not ACL and
+  not a missing migration. A permission failure would be `EZ-1`; an unknown field `EV-8`/`EV-9`.
+- **Check both directions before debugging anything else.** Count rows in
+  `PurchaseOrders_SalesOrders` and `SalesOrders_PurchaseOrders` for the order. If upstream = 1 and
+  downstream = 0, the caller is on the wrong route. This diagnosis is one query and saves hours.
+- **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.
+
+## Change history
+- 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/dbchanges2/INDEX.md

@@ -8,3 +8,4 @@
 | [Auditing a client DB that drifted from its models (partially applied module migration)](workflows/client-schema-drift-audit.md) | A recurring 2.0 failure mode: **one client's database drifts from what the PHP models declare**, usually because a `_modules/<module>/` migration was applied to | dbchanges2/Client_Growrk/2026-05-28.sql, dbchanges2/Client_Growrk/2026-08-10c - GrowrkServiceRequestCustomFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10d - GrowrkServiceRequestTypeAndDispositionSeeds.sql, dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Growrk/2026-08-10 - GrowrkUnitInventoryFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10b - GrowrkUnitItemDescriptionAcl.sql, dbchanges2/Client_Growrk/_modules.txt |
 | [Local vs prod MySQL config parity — why “it passed locally” is not evidence](workflows/local-vs-prod-mysql-config-parity.md) | Several migration failures that look like "prod-only bugs" are actually **per-machine MySQL server-configuration differences**. |  |
 | [Repairing non-prod metadata drift (works in prod, broken in beta/dev-sandbox)](workflows/nonprod-metadata-drift-repair.md) | Almost all 2.0 platform behavior is **metadata** — `Core.Records`/`RecordFields`, `Core.RecordScripts`, `Core.ApiPayloadInterceptors`, and per-client `Acl*` row | dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql, dbchanges2/Client_Compass/2026-08-06 - RemoveBrokenSalesOrderItemPostPostInterceptor.sql, dbchanges2/Core/2026-07-16a - TrackingNumberSignatureTypeRecordField.sql, dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Aig/_modules.txt, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql, api2/Config/beta.ini, api2/Config/sandbox-dev.ini, dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql, dbchanges2/Client/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql |
+| [Verifying whether a dbchanges2 migration actually ran in an environment](workflows/verifying-a-migration-ran.md) | dbchanges2 has no execution ledger you can query — "did this file run here?" has to be answered from the **rows the file would have produced**. | Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql, Client/2026-08-13 - UnitsForItemsPO_SalesOrderItemsJoin.sql |

package/knowledge/2.0/apps/dbchanges2/workflows/verifying-a-migration-ran.md

@@ -0,0 +1,58 @@
+---
+title: "Verifying whether a dbchanges2 migration actually ran in an environment"
+framework: "2.0"
+repo: dbchanges2
+project: Database Changes
+client: shared
+type: workflow
+status: active
+updated: 2026-08-25
+owners: [apeterson]
+files:
+  - Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql
+  - Client/2026-08-13 - UnitsForItemsPO_SalesOrderItemsJoin.sql
+related:
+  - ../architecture.md
+  - ../features/surface-layer-schema.md
+---
+
+## Summary
+
+dbchanges2 has no execution ledger you can query — "did this file run here?" has to be answered
+from the **rows the file would have produced**. This procedure gets a reliable answer, and names
+the two ways the naive answer is wrong.
+
+## Steps
+
+1. **Preferred — match the hardcoded uuid.** If the migration inserts a literal v4 uuid, select on
+   it. Present ⇒ this file ran. This is the only check that identifies the *file* rather than the
+   *effect*.
+2. **Fallback — match the structural signature.** When the uuid column is unavailable or the row
+   was seeded with `UUID()`, select on the **exact column-value combination** the file writes.
+   Worked example — `Client/2026-08-13 - UnitsForItemsPO_SalesOrderItemsJoin.sql` was confirmed on
+   `Client_Nychh` by a `TableViewJoins` row with `sortOrder = 23`, `joinRecordId = 15`,
+   `joinOnRecordFieldId = 60`, `parentRecordFieldId = 368`, `type = OUTER`, on the tableview slug
+   `units-for-items-for-purchase-orders`.
+3. **For a guarded file, find its distinguishing side-effect.** Pick something in the file that a
+   pre-existing row would *not* already have — typically the ACL grant pair it adds. Worked example
+   — `Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql` was confirmed on `Client_Nychh` by the
+   grant pair **exactly Base + API, `isWritable = 0`**; Compass already had `_purchaseOrders` as
+   `CustomRecordFields` id 77 under a *different* uuid, so the field row alone proved nothing.
+4. **State the conclusion as "the effect is present in env X"**, not "the file ran", unless step 1
+   succeeded.
+
+## Gotchas
+
+- **A guarded `INSERT ... WHERE NOT EXISTS` is a NO-OP where the row already exists under a
+  different uuid.** Therefore: *row absent* ≠ "the file did not run", and *row present* ≠ "this
+  file created it". Both directions of the naive inference are unsound.
+- Seed rows created with `UUID()` differ per environment, so cross-environment uuid comparison is
+  meaningless. Compare **ids and structure**, not uuids. (Same reason surface migrations key on the
+  literal `id` — see [Surface Layer Schema](../features/surface-layer-schema.md).)
+- Fan-out folders (`Client/`) run per tenant, so a file can be present in one client schema and
+  genuinely absent in another. Always verify against the specific schema, not "the environment".
+
+## Change history
+- 2026-08-25 — Captured the uuid-first / structural-signature-fallback procedure and the
+  guarded-insert unsoundness, after confirming `Client/2026-08-11b` and `Client/2026-08-13` on
+  `Client_Nychh` in sandbox-client (apeterson)

package/knowledge/INDEX.md

@@ -18,10 +18,10 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 62 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 66 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 56 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 25 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
-- **dbchanges2** (Database Changes) _(framework core)_ — 8 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
+- **dbchanges2** (Database Changes) _(framework core)_ — 9 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 7 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 4 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **toga2-view** (TOGa View Frontend) — 12 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)

package/knowledge/clients/compass-usa/profile.md

@@ -22,6 +22,7 @@ updated: 2026-08-25
 owners: [jcardinal, bala, tcox, apeterson, dfranks]
 files: []
 related:
+  - ../../2.0/apps/_underscore/features/sales-order-po-number-sourcing.md
   - features/persona-model-and-levy-gating.md
   - features/people-file-user-lifecycle.md
   - workflows/persona-refactor-migration.md

package/knowledge/clients/nychh/INDEX.md

@@ -2,4 +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 |
 | [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

@@ -0,0 +1,59 @@
+---
+title: "NYCHH PO links are UPSTREAM — the downstream SO→PO route returns empty"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: nychh
+type: client-feature
+status: active
+updated: 2026-08-25
+owners: [apeterson]
+files:
+  - _underscore/Model/Client/SalesOrder.php
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts
+  - dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.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
+  - ../profile.md
+---
+
+## Summary
+
+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.
+
+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
+order. The front end was calling the **downstream** route; the list column's table-view join uses
+the **upstream** table.
+
+## How it works
+
+- Verified on `Client_Nychh` (sandbox-client) for the affected order: **upstream = 1 row,
+  downstream = 0 rows**.
+- The API returned `200` with `totalRecordCount 0` and **no** `EZ-*`/`EV-*` messages — the
+  signature of a join matching nothing, not of a permission or field-resolution failure.
+- **ACL was clean and was ruled out:** `AclRecordPermissions` on records **275 and 276** both grant
+  `roleId` 1 and 3 full CRUD in `Client_Nychh`; the JWT carried client roles `[1,2]`. This is *not*
+  the Compass Canada-style role mis-seed.
+- Both relevant migrations were confirmed to have run on `Client_Nychh`
+  (`Client/2026-08-11b`, `Client/2026-08-13`) — see
+  [verifying a migration ran](../../../2.0/apps/dbchanges2/workflows/verifying-a-migration-ran.md).
+
+## 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.
+- Do not "fix" this by adding downstream rows. The direction is correct for NYCHH's business model;
+  the shared field is what is incomplete.
+
+## Change history
+- 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/knowledge/clients/nychh/profile.md

@@ -23,6 +23,8 @@ files:
 related:
   - ../../2.0/apps/_underscore/features/tracking-number-bridges.md
   - ../../2.0/apps/_underscore/features/tableview-joins.md
+  - ./features/po-number-upstream-direction.md
+  - ../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md
 ---
 
 ## Summary
@@ -52,6 +54,11 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   tag added after the ItemShip never bumps the fulfillment sync. See
   [NYCHH Asset-Tag Backfill](../../2.0/apps/worker2/features/nychh-asset-tag-backfill.md).
 
+- **PO links are UPSTREAM (`PurchaseOrders_SalesOrders`), not downstream.** The downstream
+  `sales-order-purchase-orders` route returns an empty array for NYCHH by design, and the shared
+  `_purchaseOrders` field (downstream-only) resolves to `null` for this tenant — open gap. See
+  [NYCHH PO Number direction](./features/po-number-upstream-direction.md).
+
 ## Notes
 - Tracking data: record 318 (item-level) is currently empty for this client; their tracking
   populates the IF/shipment level (record 317). The rebuilt views use 318 (per the Compass

package/knowledge/clients/quad/INDEX.md

@@ -2,5 +2,6 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
+| [Quad Enter PO Details — single-vendor-by-country selection and the EV-12 `vendorItem` failure](features/enter-po-details-vendor-selection-ev12.md) | 2.0 | Adding a PO number for Quad through **Enter PO Details** can `400` with **`EV-12` "unable to find a unique match"** on field **`vendorItem`**. | _underscore/Model/Quad/PurchaseOrder.php |
 | [Quad: PO + ASN email importer (import_po_and_asn.php)](features/po-asn-email-import.md) | 1.0 | Quad Graphics' supplier emails Purchase Order and Advance Shipping Notice CSVs into a monitored Microsoft 365 mailbox. | worker/crons/toga2/quad/import_po_and_asn.php |
 | [Quad Graphics](profile.md) | 2.0 | Quad Graphics is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Quad`. |  |

package/knowledge/clients/quad/features/enter-po-details-vendor-selection-ev12.md

@@ -0,0 +1,62 @@
+---
+title: "Quad Enter PO Details — single-vendor-by-country selection and the EV-12 `vendorItem` failure"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: quad
+type: client-feature
+status: active
+updated: 2026-08-25
+owners: [apeterson]
+files:
+  - _underscore/Model/Quad/PurchaseOrder.php
+related:
+  - ../../../2.0/apps/api2/features/v2-api-error-codes.md
+  - ../../../2.0/apps/_underscore/features/sales-order-po-number-sourcing.md
+  - ../../../2.0/standards/backend-php.md
+  - ../profile.md
+---
+
+## Summary
+
+Adding a PO number for Quad through **Enter PO Details** can `400` with
+**`EV-12` "unable to find a unique match"** on field **`vendorItem`**. The failure is a **code
+defect plus a country-scoped catalog coverage gap** — not a bad data reset and not ACL. Quad's
+`Client_Quad` data was verified healthy (592 `VendorItems`, 18 active vendors, 15 with a complete
+`Vendors → Addresses → States → Countries` chain).
+
+## How it works
+
+1. The FE payload contains **no items**. Quad's `prePost` interceptor
+   (`_underscore/Model/Quad/PurchaseOrder.php:9` → `populatePurchaseOrderFromSalesOrder`) builds
+   them from the sales order's lines.
+2. `getVendorByCountry` (line ~186) picks **one vendor for the whole PO**: first the vendor covering
+   the **most** of the order's items *in the ship-to country*, else **any** vendor in that country.
+3. Line ~79 then restricts the `VendorItems` join to that **single** vendor.
+4. When the chosen vendor has no `VendorItems` row for a line, lines ~127-139 fall back to sending a
+   **descriptor** (`vendor` + `item` + `vendorPartNumber`).
+
+## Gotchas
+
+- 🚨 **The descriptor fallback cannot work — its comment is wrong.** The comment claims the API can
+  "create/match" the descriptor. The field's child policy is **`MATCH`**, which only *looks up* and
+  **never creates**. Zero matches (or 2+) ⇒ `EV-12`. This is the primary defect.
+- **Real-world instance:** order ships to Poland; picked vendor **Bechtle Direct Polska** (PL,
+  correct); item **MGDN4HN/A** is mapped **only** to General Technologies (IN, India). No Polish
+  supplier for the part ⇒ `EV-12`. Reproduced on a second order with a different vendor/item pair —
+  it is **systemic**, not one-off.
+- 🚨 **Secondary defect — nondeterministic vendor choice.** `getVendorByCountry`'s ranking query is
+  `ORDER BY vendorItemCount DESC LIMIT 1` with **no tie-break column**. On tied counts the winner is
+  arbitrary and can **change after a database reload** (row order/ids move). This is exactly the
+  hazard in [backend-php standards](../../../2.0/standards/backend-php.md) ("a `LIMIT 1` on a
+  non-unique key MUST have a deterministic `ORDER BY`"). Fix is to append `, v.id`.
+- **A vendor with a broken address link is invisible to vendor selection.** The queries require the
+  full `Vendors → Addresses → States → Countries` chain; a vendor missing any hop is silently
+  skipped and the PO is silently handed to a different vendor.
+- **Recommended remediation (not yet applied):** raise a useful error naming the chosen vendor and
+  the unmapped item instead of an opaque `EV-12`, and add the deterministic tie-break.
+
+## Change history
+- 2026-08-25 — Diagnosed EV-12 on `vendorItem` as the `MATCH`-policy descriptor fallback that can
+  never create, driven by single-vendor-by-country selection against a country-scoped catalog gap;
+  also recorded the missing `LIMIT 1` tie-break in `getVendorByCountry` (apeterson)

package/knowledge/clients/quad/profile.md

@@ -20,6 +20,8 @@ owners: ["jcardinal", "bala", "apeterson", "ajean"]
 files: []
 related:
   - ./features/po-asn-email-import.md
+  - ./features/enter-po-details-vendor-selection-ev12.md
+  - ../../2.0/apps/_underscore/features/sales-order-po-number-sourcing.md
   - ../../2.0/apps/_underscore/features/tracking-number-bridges.md
   - ../../2.0/apps/_underscore/features/item-fulfillment-stage-lifecycle-and-order-status.md
   - ../../2.0/apps/_underscore/features/surface-resolver.md

package/package.json

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