toga-ai 1.0.651 → 1.0.652

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,7 +32,7 @@
 | [_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 |

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
+  - ./purchase-order-sales-order-bridges.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](./purchase-order-sales-order-bridges.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
+  - purchase-order-sales-order-bridges.md
   - ../../toga2-supply/features/fulfill-and-ship.md
   - ../../api2/features/record-scripts.md
 ---
@@ -40,6 +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.
+
 ## ⚠ 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 +101,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 **reverse** bridge
+  (`PurchaseOrders_SalesOrders`, customer PO), while the shared `SalesOrders._purchaseOrders`
+  calculated field read the **forward** 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)
 - 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/api2/INDEX.md

@@ -19,7 +19,7 @@
 | [TOGa IQ Sprint Dashboard API (Record Scripts)](features/sprint-dashboard-api.md) | The internal **TOGa IQ sprint dashboard** is served in production by **six api2 Record Scripts** on `_Model_Team_Sprint` (`_underscore/Model/Team/Sprint.php`), | _underscore/Model/Team/Sprint.php, api2/Component/Api/V2/V2.php, dbchanges2/Core/2026-07-24a - SprintDashboardRecordScripts.sql, dbchanges2/Client_True/2026-07-24b - SprintDashboardScriptAcl.sql |
 | [Surface action-state via the surface=<slug> request option (M2M-safe)](features/surface-meta-option.md) | An opt-in V2 engine request option, `surface=<slug>`, that attaches per-record UI action state (`isVisible`/`isEnabled`) to a GET response **under `meta.surface | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Surface.php |
 | [TableView row-filtering via apiWhereClause (options.where grammar, end to end)](features/tableview-apiwhereclause-row-filtering.md) | `TableViews.apiWhereClause` (TEXT, nullable) is the sanctioned, code-free way to restrict or exclude rows from a 2.0 table view. | api2/Component/Api/V2/V2.php, _underscore/Model/Client/TableView.php, toga2-supply/src/api/toga.ts |
-| [TableView field/column metadata (TableViewFields, hidden projected columns)](features/tableview-field-metadata.md) | The columns of a 2.0 table view are defined by DB metadata, not code. | _underscore/Model/Client/TableView.php, api2/Component/Api/V2/V2.php, dbchanges2/Client/2026-07-20 - ItemsUuidForPurchaseOrderItemsTableView.sql, dbchanges2/Core/2026-08-17a - ItemFulfillmentQuantityFieldTypeNumber.sql, dbchanges2/Client/2026-08-17a - ItemFulfillmentColumnsCopyable.sql, dbchanges2/Client_Quad/2026-08-18c - SalesOrderListingSortByDateOrderDesc.sql, dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql |
+| [TableView field/column metadata (TableViewFields, hidden projected columns)](features/tableview-field-metadata.md) | The columns of a 2.0 table view are defined by DB metadata, not code. | _underscore/Model/Client/TableView.php, api2/Component/Api/V2/V2.php, dbchanges2/Client/2026-07-20 - ItemsUuidForPurchaseOrderItemsTableView.sql, dbchanges2/Core/2026-08-17a - ItemFulfillmentQuantityFieldTypeNumber.sql, dbchanges2/Client/2026-08-17a - ItemFulfillmentColumnsCopyable.sql, dbchanges2/Client_Quad/2026-08-18c - SalesOrderListingSortByDateOrderDesc.sql, dbchanges2/Client_Quad/2026-08-24 - Quad Multi Currency Item Pricing.sql, dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql |
 | [Tickets API (/v2/tickets)](features/tickets-api.md) | The generic ticket endpoint of the 2.0 REST API. | Component/Api/V2/V2.php |
 | [V2 API error/message codes (EV/EZ troubleshooting map)](features/v2-api-error-codes.md) | The V2 JSON engine (`Component/Api/V2/V2.php`) returns short **message codes** in the response `error` field, grouped by family: `EN-*` authentication, `EZ-*` a | api2/Component/Api/V2/V2.php, api2/Component/Api/V2/Response/Response.php, api2/Component/Api/V2/Response/Oauth/Oauth.php, api2/Controller/Index.php, toga2-supply/src/globalTypes.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, toga2-supply/src/api/toga.ts, _underscore/Model/Client/TrackingNumber.php |
 | [V2 request deadlock-retry — route-scoped in-process replay](features/v2-deadlock-retry.md) | api2's front controller can **detect a MySQL deadlock (1213) / lock-wait timeout (1205) and replay the whole request in-process**, so a transient lock collision | api2/Controller/Index.php, _underscore/Database.php, _underscore/Query.php |

package/knowledge/2.0/apps/api2/features/nested-relationship-writes.md

@@ -6,13 +6,14 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-20
+updated: 2026-08-26
 owners: ["bala", "mhammontree", "tcox"]
 files:
   - api2/Component/Api/V2/V2.php
   - _underscore/Model/Client/ContactEmailAddress.php
 related:
   - ../architecture.md
+  - ../../toga2-supply/features/currency-amount-lines-editor.md
   - cxml-shipnotice-gateway.md
   - ../../../clients/aig/features/entitlement-intake.md
   - ../../ai-bdr/features/web-funnel-app.md
@@ -293,6 +294,23 @@ anywhere — no `messages[]`, nothing in the client `Logs` or the core/writer `L
   **double-wrapped** (`entitlementEntitlementCoverageTypes: [{entitlementCoverageType: {…}}]`).
   Both shapes routinely appear in the *same* payload, so the sibling collections actively mislead.
 
+## ⚠ The UPDATE path reports 200 even when a CHILD write FAILED
+
+The V2 **update** branch sets the response status to **200 unconditionally after its children
+loop**, so a nested `PUT` on a parent comes back `isSuccess: true` even when a child insert/update
+was rejected (a unique-key violation, an ACL denial). The parent-level status is not a verdict on
+the children.
+
+**Consequence for any parent-with-children editor: do not save child rows as a nested `PUT` on the
+parent if you need to know whether they landed.** Issue the child writes **directly against the
+child route** and check each response individually. Found 2026-08-26 while building the
+per-currency price/cost line editors for Quad, where a unique-key rejection on one line was
+completely invisible to the UI — see
+[per-currency amount lines](../../toga2-supply/features/currency-amount-lines-editor.md).
+
+Same family as the 201-with-dropped-data case above: **a success status from V2 proves only that the
+parent was written.** Assert child row counts, or write children explicitly.
+
 ## Gotcha
 
 - **Nested write with only a non-identifier field silently creates duplicates.** This is a
@@ -304,6 +322,12 @@ anywhere — no `messages[]`, nothing in the client `Logs` or the core/writer `L
 
 ## Change history
 
+- 2026-08-26 — Added: **the UPDATE path sets status 200 unconditionally after its children loop**, so
+  a nested `PUT` reports success even when a child write failed (unique-key rejection, ACL denial).
+  Any parent-with-children editor that needs to know whether the children landed must write them
+  directly against the child route and check each response. Found while building Quad's per-currency
+  price/cost line editors. (bala)
+
 - 2026-08-20 — Documented that **`overrideChildPolicy` (not just `overrideIsIdentifier`) is per-API
   provisioning**, and that a *missing* `Apis_RecordFields` row is a silent 100%-rejection outage:
   Compass Canada's cXML API had zero rows and the Core defaults for the ASN **item**/**header**

package/knowledge/2.0/apps/api2/features/tableview-field-metadata.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-18
+updated: 2026-08-26
 owners: [apeterson, bala]
 files:
   - _underscore/Model/Client/TableView.php
@@ -15,10 +15,13 @@ files:
   - dbchanges2/Core/2026-08-17a - ItemFulfillmentQuantityFieldTypeNumber.sql
   - dbchanges2/Client/2026-08-17a - ItemFulfillmentColumnsCopyable.sql
   - dbchanges2/Client_Quad/2026-08-18c - SalesOrderListingSortByDateOrderDesc.sql
+  - dbchanges2/Client_Quad/2026-08-24 - Quad Multi Currency Item Pricing.sql
   - dbchanges2/Client_Elite/2026-08-18 - InventoryUnitsItemColumns.sql
   - dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql
 related:
   - tableview-apiwhereclause-row-filtering.md
+  - ../../_underscore/features/page-meta-context-field-settings.md
+  - ../../_underscore/features/acl-permission-chain.md
   - ../../toga25-supply/features/meta-driven-table-data.md
   - ../../_underscore/features/tableview-joins.md
 ---
@@ -53,6 +56,40 @@ the column's type/format **everywhere that field appears, for every client**. Th
 intended canonical behavior — if you only want the change in one view, this mechanism cannot do
 it. (Reference: `Core.RecordFields` id 369 = `ItemFulfillmentItems.quantity` set to
 `type=NUMBER`, `precision=0`, which normalizes that column across all fulfillment views/clients.)
+
+#### Per-client type override — point the column at a same-named `CustomRecordFields` row {#per-client-type-override}
+
+"No per-view override" is about `TableViewFields` having no `type` column of its own. It does
+**not** mean a client is stuck with the Core type: a column does not have to point at a Core
+`RecordField` at all. `TableViewFields.customRecordFieldId` is the alternative to `recordFieldId`,
+so **one client can retype a column without touching Core**:
+
+1. Insert a `Client_<X>.CustomRecordFields` row with the **same `field` name** as the Core
+   `RecordField` (e.g. `_unitPrice`) and the wanted `type` (e.g. `STRING`).
+2. Repoint that client's `TableViewFields` row at `customRecordFieldId` instead of
+   `recordFieldId`.
+
+Why this is safe rather than a hack:
+
+- **Reads** — for a **calculated** (`FIELD_SQL`) field the API resolves the expression off the
+  model by NAME, so it does not care which metadata table the column came from.
+- **Writes** — the V2 write path accepts the payload key from **either** lookup:
+  `api2/Component/Api/V2/V2.php` ~L4801 ORs `array_key_exists($key, $lookupRecordFieldByField)`
+  with `$lookupCustomRecordFieldByField` (and again for the `<key>Id` suffix form).
+- **ACL** — **do not add an `AclCustomFieldPermissions` row** when the field name is already
+  granted through the Core `RecordField`'s `AclFieldPermissions` row. It is unnecessary, and it is
+  actively wrong: it would keep the column readable after the Core grant is revoked. See
+  [ACL permission chain](../../_underscore/features/acl-permission-chain.md).
+- **Header labels do NOT follow.** A custom-record-field column's label rows land in a page-meta
+  bucket the grid never reads, so the label must still come from the Core field — see
+  [legacy page meta](../../_underscore/features/page-meta-context-field-settings.md).
+
+Worked example (Quad, 2026-08-26): `_unitPrice` (Core `RecordFields` **909**, `CURRENCY`) and
+`_unitCost` (Core **906**, `CURRENCY`) were retyped to `STRING` for `Client_Quad` only, so those
+columns render multi-currency text (`PLN 5295.00, USD 1310.00`) instead of a dollar-formatted
+number — Core is shared with every other client and was left untouched.
+`dbchanges2/Client_Quad/2026-08-24 - Quad Multi Currency Item Pricing.sql`. This is currently the
+**only** client-scoped way to change a column's rendering type.
 - **`Client_*.TableViewJoins`** — the view's joins; also drive `options.join`/`ojoin` on the data
   request (see [tableview-apiwhereclause-row-filtering](tableview-apiwhereclause-row-filtering.md)).
   How a join row becomes SQL — aliasing, chained multi-hop joins, and the ACL row the joined record
@@ -173,6 +210,15 @@ SalesOrderListingSortByDateOrderDesc.sql`).
   `isSortable`, `isFilterable`, `isVisible` are the per-view knobs (on `TableViewFields`).
 
 ## Change history
+- 2026-08-26 - Added the **per-client type override**: a column can point at
+  `TableViewFields.customRecordFieldId` instead of `recordFieldId`, so registering a
+  `Client_<X>.CustomRecordFields` row with the **same field name** as the Core RecordField and the
+  wanted `type` retypes the column for that client only. Safe because a calculated field resolves off
+  the model by name and the V2 write path ORs both field lookups (`V2.php` ~L4801); **no
+  `AclCustomFieldPermissions` row should be added** when the name is already granted through the Core
+  field (it would survive a revoke of the Core grant), and header labels still have to come from the
+  Core field. Shipped for Quad's `_unitPrice` (Core 909) / `_unitCost` (Core 906), CURRENCY → STRING,
+  in `dbchanges2/Client_Quad/2026-08-24 - Quad Multi Currency Item Pricing.sql`. (bala)
 
 - 2026-08-18 — Documented DB-driven **default sort**: `TableViews.sortPrimaryTableViewFieldId`
   (+ `sortPrimaryDirection`, and the secondary pair) FK into `TableViewFields`, emitted as

package/knowledge/2.0/apps/toga2-supply/INDEX.md

@@ -3,8 +3,10 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [TOGa Supply (toga2-supply) Architecture](architecture.md) | `toga2-supply` is the **React + Vite frontend** for TOGa Supply — warehouse fulfillment tooling (shipment selection, fulfill & ship against carrier APIs, NetSui | toga2-supply/src/api/toga.ts, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx |
+| [Per-currency amount lines (CurrencyAmountLines / CurrencyAmountList) and child-row diffing](features/currency-amount-lines-editor.md) | The shared UI for "one amount per currency" on a parent record — an item's prices, a vendor item's costs. | toga2-supply/src/components/ui/CurrencyAmountLines.tsx, toga2-supply/src/pages/Items/api/itemsApi.ts, toga2-supply/src/pages/VendorItems/api/vendorItemsApi.ts |
 | [Fulfill & Ship](features/fulfill-and-ship.md) | Fulfill & Ship lets a warehouse user select sales-order line items, enter serials, pick a carrier/method, and in one action: create the Item Fulfillment records | _underscore/Trait/Netsuite/SalesOrder.php, dbchanges2/Client_Growrk/2026-08-10e - GrowrkUpsServiceMethodCodes.sql, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, _underscore/Model/Client/Measure.php, _underscore/Model/Client/TrackingNumber.php, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/getEditShipmentFormOptions.ts, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/validateFormOnSubmit.ts, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/checkDimensions.ts, toga2-supply/src/components/ui/Tables/BasicTable/BasicTable.tsx, toga2-supply/src/components/ui/Tables/types.ts, toga2-supply/src/components/ui/GoogleMapsLink.tsx, toga2-supply/src/pages/ShipmentItems/view/forms/ShipmentItemsTable.tsx, toga2-supply/src/pages/ShipmentItems/api/ShipmentItemsApi.ts, toga2-supply/src/pages/ShipmentItems/types.ts, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/RETURNLABELFIELDS.json, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/components/ui/BaseInput/UnitSelect.tsx, toga2-supply/src/pages/EditShipment/view/modals/SerialNumbersModal.tsx, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/pages/EditShipment/view/components/SelectedShipmentItemsTable.tsx, toga2-supply/src/pages/EditShipment/view/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/DUMMYUPDATESHIPMENTFIELDS.json, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/tailwind.config.cjs, toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx, toga2-supply/src/styles/index.scss, toga2-supply/src/components/ui/BaseInput/BaseInput.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/EditShipment/viewModel/signatureTypes.ts, toga2-supply/src/pages/EditShipment/view/modals/SelectReturnAddressModal.tsx, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/formatShipmentData.ts, toga2-supply/src/pages/EditShipment/types.ts, toga2-supply/src/pages/Shipments/view/ShipmentsPage.tsx, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, toga2-supply/src/pages/Shipments/types.ts, toga2-supply/src/pages/FulfilledShipments/view/FulfilledShipmentsPage.tsx, toga2-supply/src/components/ui/CardTable/CardTable.tsx, toga2-supply/src/components/ui/CardTable/types.ts, toga2-supply/src/assets/pen-line.svg, _underscore/Model/Client/ItemFulfillment.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php |
-| [Order-details field config (valueKey resolution) & the hardcoded Customer name](features/order-detail-field-config-and-customer-name.md) | The supply order-details modal is **config-driven**: each host has a JSON field list under `src/pages/Orders/view/OrderView/viewModel/FIELDS/<HOST>/`, and every | toga2-supply/src/utils/formatCustomerName.tsx, toga2-supply/src/pages/Orders/view/OrderView/components/invoices/OrderContentSection.tsx, toga2-supply/src/pages/Orders/view/OrderView/viewModel/FIELDS/, toga2-supply/src/api/toga.ts |
+| [Order-details field config (valueKey resolution) & the hardcoded Customer name](features/order-detail-field-config-and-customer-name.md) | The supply order-details modal is **config-driven**: each host has a JSON field list under `src/pages/Orders/view/OrderView/viewModel/FIELDS/<HOST>/`, and every | toga2-supply/src/utils/formatCustomerName.tsx, toga2-supply/src/pages/Orders/view/OrderView/components/invoices/OrderContentSection.tsx, toga2-supply/src/pages/Orders/view/OrderView/viewModel/FIELDS/, toga2-supply/src/pages/Orders/view/OrderView/viewModel/useOrderDetailsViewModel.ts, toga2-supply/src/api/toga.ts |
+| [Table-data request filters (`additionalData` → `getDataTableData`)](features/table-data-additional-filters.md) | A listing page adds its own row filters to a table-view data request by passing an **`additionalData`** prop down to the shared `useFetchData` hook, which forwa | toga2-supply/src/components/ui/Tables/hooks/useFetchData.tsx, toga2-supply/src/api/toga.ts, toga2-supply/src/pages/VendorItems/VendorItemsPage.tsx |
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-supply` (React + Vite) builds and deploys on **AWS Amplify**. | toga2-supply/amplify.yml, toga2-supply/.gitattributes, toga2-supply/.github/workflows/sync-stage-environments.yml, toga2-supply/.env.qc-security |
 | [Onboarding a client to the supply2 frontend (host-scoping)](workflows/client-host-scoping.md) | How a new tenant becomes a "client" in the `toga2-supply` frontend. | toga2-supply/src/stores/useHostNameStore.ts, toga2-supply/src/utils/resolveClientHostName.ts, toga2-supply/src/hooks/useHostName.tsx, toga2-supply/src/hooks/usePageDetails.tsx, toga2-supply/src/hooks/usePageListDetails.tsx, toga2-supply/src/components/layout/SlideMenu/SlideMenu.tsx, toga2-supply/src/utils/handleClientAuthentication.ts, toga2-supply/src/App.tsx, toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts, toga2-supply/src/pages/Inventory/viewModel/FIELDS/INVENTORYPAGEFIELDS.ts, toga2-supply/src/pages/Inventory/listing/InventoryPage.tsx, toga2-supply/src/pages/Inventory/listing/InventoryRouter.tsx, toga2-supply/src/pages/Inventory/listing/InventorySubTablePage.tsx, toga2-supply/src/pages/Orders/OrdersPage.tsx, toga2-supply/src/pages/Orders/viewModel/useOrdersPageViewModel.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, toga2-supply/src/pages/Orders/view/OrderView/viewModel/useOrderDetailsViewModel.ts, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/renderModalContent.tsx, toga2-supply/src/utils/convertConstructorColumnTitles.ts, toga2-supply/src/api/toga.ts, toga2-supply/package.json |
 | [Onboarding a client to TOGa Supply Fulfill & Ship](workflows/onboarding-a-client-to-fulfill-and-ship.md) | **Onboarding a client to Fulfill & Ship is CONFIGURATION, not development** — unless the client wants tracking pushed into their own system. | _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Trait/Netsuite/ItemFulfillment.php, dbchanges2/_modules/netsuite/ |

package/knowledge/2.0/apps/toga2-supply/features/currency-amount-lines-editor.md

@@ -0,0 +1,83 @@
+---
+title: Per-currency amount lines (CurrencyAmountLines / CurrencyAmountList) and child-row diffing
+framework: "2.0"
+repo: toga2-supply
+project: TOGa Supply
+client: shared
+type: feature
+status: active
+updated: 2026-08-26
+owners: [bala]
+files:
+  - toga2-supply/src/components/ui/CurrencyAmountLines.tsx
+  - toga2-supply/src/pages/Items/api/itemsApi.ts
+  - toga2-supply/src/pages/VendorItems/api/vendorItemsApi.ts
+related:
+  - ../architecture.md
+  - ../workflows/client-host-scoping.md
+  - ../../api2/features/nested-relationship-writes.md
+  - ../../../../clients/quad/features/multi-currency-item-pricing.md
+---
+
+## Summary
+
+The shared UI for "one amount per currency" on a parent record — an item's prices, a vendor item's
+costs. Two components: **`CurrencyAmountLines`** (editable, `useFieldArray`) for the create/edit
+modals, and **`CurrencyAmountList`** (read-only) for the detail views. First consumer is Quad's
+multi-currency item pricing, gated by host (`localStorage` `hostName === 'QUAD'`), but the
+components and — more importantly — the **save/diff rules below are generic**: they apply to any
+parent whose children are unique per `(parent, type, currency)`.
+
+## How it works
+
+- **Editable lines** — `CurrencyAmountLines` drives a `useFieldArray` list of `{currency, amount}`
+  rows inside the parent's form: add a line, pick a currency, type an amount, remove a line.
+- **Read-only lines** — `CurrencyAmountList` deliberately **does not use form context.** The detail
+  modals render their view mode **outside** the `FormProvider`, so a read-only component that calls
+  `useFormContext()` throws there. Keep the read-only variant context-free; do not "simplify" the
+  two components into one that always reads the form.
+- **Host gating** — the lines are wired into the item and vendor-item create/edit modals behind the
+  host check, per the escape-hatch rule in
+  [client host-scoping](../workflows/client-host-scoping.md).
+- **Saving** — the parent save diffs the on-screen lines against the rows that were loaded, then
+  issues explicit child writes (see the rules below). Existing rows carry their `uuid`; new lines
+  do not.
+
+## ⚠ Diffing rules — a currency change is a DELETE + CREATE, never an UPDATE
+
+The child tables are UNIQUE on `(parentId, priceTypeId, currencyId)`, and that unique key is what
+makes the naive diff fail:
+
+1. **A line whose CURRENCY moved cannot be issued as an UPDATE.** The currency it moves onto may
+   still be held by another line, so the update is rejected by the unique key. A straight two-line
+   currency swap fails **both** ways and writes nothing at all.
+2. **Deleting first is not sufficient on its own.** It only helps when the colliding row is itself
+   being deleted, which is exactly what a swap is not.
+3. **Correct shape:** reclassify a currency-moved line as **a delete of the old row plus a create
+   of the new one**, then **run all deletes before all creates**. With that ordering an N-way
+   currency rotation resolves in a single pass. Only an amount-only change stays an UPDATE.
+4. **Do not send the children as a nested `PUT` on the parent.** The V2 update branch sets status
+   **200 unconditionally after its children loop**, so a failed child reports success — see
+   [nested-relationship writes](../../api2/features/nested-relationship-writes.md). Write each child
+   against its own route and check each response.
+5. **Refresh the diff baseline after ANY save attempt, not only a fully successful one.** Otherwise
+   a retry re-sends writes that already landed (duplicate creates, deletes of rows that are gone).
+
+## Gotchas
+
+- A read-only currency list that reaches for form context works in the edit modal and throws in the
+  view modal — the two render on opposite sides of the `FormProvider`.
+- A calculated field that returns the concatenated per-currency text must be declared as plain
+  `FIELD_SQL` on the model, or the value is cast to `0` before it ever reaches the grid — see
+  [FIELD_SQL calculated fields](../../_underscore/features/calculated-sql-fields.md).
+
+## Change history
+
+- 2026-08-26 — First capture. Added the shared `CurrencyAmountLines` (editable, `useFieldArray`) and
+  `CurrencyAmountList` (read-only, intentionally context-free because view mode renders outside the
+  `FormProvider`) components, wired into the item / vendor-item create and edit modals behind
+  `hostName === 'QUAD'`. Recorded the generic diff rules for per-currency children: a currency change
+  must become delete + create (the `(parent, type, currency)` unique key rejects the update, and a
+  two-line swap otherwise writes nothing), all deletes run before all creates so an N-way rotation
+  resolves in one pass, children are written on their own routes rather than as a nested PUT, and the
+  diff baseline is refreshed after any save attempt. (bala)

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

@@ -6,17 +6,19 @@ project: TOGa Supply
 client: shared
 type: feature
 status: active
-updated: 2026-08-18
+updated: 2026-08-26
 owners: [bala]
 files:
   - toga2-supply/src/utils/formatCustomerName.tsx
   - toga2-supply/src/pages/Orders/view/OrderView/components/invoices/OrderContentSection.tsx
   - toga2-supply/src/pages/Orders/view/OrderView/viewModel/FIELDS/
+  - toga2-supply/src/pages/Orders/view/OrderView/viewModel/useOrderDetailsViewModel.ts
   - toga2-supply/src/api/toga.ts
 related:
   - ../../../../clients/elite/features/supply2-scope.md
   - ../workflows/client-host-scoping.md
   - ../architecture.md
+  - ../../_underscore/features/purchase-order-sales-order-bridges.md
 ---
 
 ## Summary
@@ -79,6 +81,44 @@ Consequences worth internalising:
 `elite.togasupply` → `ELITE`. Ten other places in the repo already compare against the literal
 `"ELITE"`, which is what makes a new map entry safe to add.
 
+## The second trap: a row renders even when the field is never requested
+
+**A field set declares the row and the fetch separately, and nothing checks that they agree.** Each
+`FIELDS/**/*.json` carries both:
+
+- a **detail row** with a `valueKey`, which decides what is *displayed*, and
+- **`apiFields.fetchOrderDetails`**, which decides what is *asked for*.
+
+api2 returns only the fields you request, so a row whose `valueKey` is missing from `apiFields`
+renders **permanently blank** no matter how correct the backend data is. There is no build-time or
+run-time warning — it is indistinguishable from an API bug or missing data.
+
+**The worked example: the purchase-order row.** `DEFAULTFIELDS.json` and all three `QUAD/*.json`
+field sets declare a row with `valueKey: "_purchaseOrders"` but omit `_purchaseOrders` from
+`apiFields.fetchOrderDetails`. `COMPASS`, `COMPASSCANADA` and `ELITE` list it in both places — which
+is the *only* reason the PO shows for those three hosts and nowhere else. Quick audit:
+
+```bash
+# 2 = declared AND requested (works).  1 = declared but never requested (blank row).
+for f in $(find src/pages/Orders/view/OrderView/viewModel/FIELDS -name '*.json'); do
+	echo "$(grep -c '"_purchaseOrders"' "$f")  $f"
+done
+```
+
+As of 2026-08-26 that still reports `1` for `DEFAULTFIELDS.json` and the three `QUAD` sets — **the
+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).
+
+### Which field set a host gets
+
+`useOrderDetailsViewModel.ts` (~L120-134) holds a `fieldMapping` keyed on `hostName` with entries
+for **`COMPASS`, `COMPASSCANADA`, `QUAD`** only, plus an early `if (hostName === "ELITE")` return.
+**Every other host falls through to `DEFAULTFIELDS`** — so NYCHH, Prudential, Canon, GroWrk and the
+rest all share one field set, and a gap in `DEFAULTFIELDS` is a gap for most of the platform. As
+with `CUSTOMER_MAP`, `hostName` is the uppercased subdomain from `src/api/toga.ts:36`.
+
 ## Making it genuinely data-driven (deliberately NOT done)
 
 The database value is available. On Elite, `Customers.name` is a single row
@@ -107,8 +147,24 @@ requires **both** changes, not either one:
   validation, so a typo or a stale key is indistinguishable from missing data. There is no build- or
   run-time check that a `valueKey` corresponds to anything the API returns.
 - `QUAD: "N/A"` is intentional — Quad's Customer row is meant to read as not-applicable.
+- **Check `apiFields` BEFORE the Network tab, and check both halves of the field set.** A blank
+  detail row is far more often a field set that never requested the field than a backend fault. Any
+  new row needs **two** edits in the same JSON: the row's `valueKey` *and* the `apiFields`
+  entry — and it needs them in **every** field set that should show it (11 of them today).
+- **A `DEFAULTFIELDS` gap hits most clients, not the edge cases.** Only four hosts have their own
+  field set; everyone else uses the default.
 
 ## Change history
+- 2026-08-26 — Added the **render-vs-request** trap: a field set declares the display row
+  (`valueKey`) and the fetch (`apiFields.fetchOrderDetails`) separately with nothing checking they
+  agree, so a declared-but-unrequested row renders permanently blank and looks like an API fault.
+  Worked example: `DEFAULTFIELDS.json` and the three `QUAD` sets declare
+  `valueKey: "_purchaseOrders"` without requesting it, which is why the PO shows only for COMPASS /
+  COMPASSCANADA / ELITE. Also recorded that `useOrderDetailsViewModel.ts`'s `fieldMapping` only
+  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)
 - 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/2.0/apps/toga2-supply/features/table-data-additional-filters.md

@@ -0,0 +1,92 @@
+---
+title: Table-data request filters (`additionalData` → `getDataTableData`)
+framework: "2.0"
+repo: toga2-supply
+project: TOGa Supply
+client: shared
+type: feature
+status: active
+updated: 2026-08-26
+owners: [bala]
+files:
+  - toga2-supply/src/components/ui/Tables/hooks/useFetchData.tsx
+  - toga2-supply/src/api/toga.ts
+  - toga2-supply/src/pages/VendorItems/VendorItemsPage.tsx
+related:
+  - ../architecture.md
+  - ../../api2/features/tableview-apiwhereclause-row-filtering.md
+  - ../../api2/features/tableview-field-metadata.md
+---
+
+## Summary
+
+A listing page adds its own row filters to a table-view data request by passing an
+**`additionalData`** prop down to the shared `useFetchData` hook, which forwards it to
+`getDataTableData` in `src/api/toga.ts`. `getDataTableData` supports **two** shapes — a single
+filter object and an array of filter objects — but **only the single-object shape actually reaches
+the API**. The array shape has never worked, and fixing it globally changes what several tenants
+see, so the array form must be avoided rather than repaired in place.
+
+## How it works
+
+1. A page renders the table with `additionalData={…}`.
+2. `useFetchData.tsx` (~L145) calls:
+
+   ```ts
+   getDataTableData(tableMeta, nestedPrimaryRecordSlug, nestedTableUuid,
+       { ...(additionalData ?? {}), page: pageToFetch }, …)
+   ```
+
+3. `getDataTableData` (`src/api/toga.ts` ~L833–900) inspects that argument: an `Array.isArray`
+   branch handles a list of filters, and an object branch handles a single filter (keyed by
+   `.slug`, plus special-cased literal keys such as `'Items.catalogId'`), turning it into the
+   `apiWhereClause` / query params on the table-view data call.
+
+## ⚠ The ARRAY form of `additionalData` is silently dropped
+
+`useFetchData` **object-spreads** `additionalData`. Spreading an array produces
+`{0: {...}, 1: {...}}` — a plain object with numeric keys. Downstream:
+
+- `Array.isArray(...)` is now **false**, so the array branch never runs;
+- the object branch finds no `.slug` on the outer object, so it contributes nothing.
+
+The filter is dropped with **no error and no warning** — the grid renders unfiltered and looks
+correct. Any page that declares its filters as an array has therefore never been filtered.
+
+## Do NOT "just fix the spread" — it changes what other tenants see
+
+`VendorItemsPage` is the **only** array-form caller in the repo, and its `Items.catalogId = 1`
+filter has consequently never applied for **any** tenant. Repairing the spread in the shared hook
+would start applying it everywhere at once. Measured in prod, that would hide:
+
+| Tenant | Vendor items that would disappear |
+|---|---|
+| Compass | 305 |
+| Prudential | 36 |
+| Elite | 1 |
+
+**Decision (2026-08-26):** leave `useFetchData` untouched and have the page pass the **single-object**
+form, which the existing object branch already handles (including the literal `'Items.catalogId'`
+key), scoped to the client that wants the filter — Quad. A latent bug in a shared hook is not a free
+fix when the "correct" behavior is a data-visibility change for tenants nobody asked about.
+
+## Rules
+
+- **Pass `additionalData` as a single OBJECT.** Treat the array branch in `getDataTableData` as dead
+  code; do not add new array-form callers.
+- **Prove a filter is applied before trusting it** — compare the row count with and without it, or
+  read the outgoing request in the Network tab. Silence is not evidence.
+- **Before repairing any shared-hook filter bug, count the rows it would start hiding, per tenant.**
+  Turning a dormant filter on is a behavior change for every client that shares the page.
+- Row filtering that should apply for *everyone* belongs in the backend
+  (`TableViews.apiWhereClause`), not in a page-level filter prop — see
+  [tableview apiWhereClause row filtering](../../api2/features/tableview-apiwhereclause-row-filtering.md).
+
+## Change history
+
+- 2026-08-26 — First capture. Documented that `useFetchData` object-spreads `additionalData`, so the
+  **array** form collapses to `{0:…,1:…}` and is silently dropped by `getDataTableData`
+  (`Array.isArray` false, no `.slug` on the outer object). `VendorItemsPage` was the only array-form
+  caller, so its `Items.catalogId = 1` filter had never applied for any tenant; fixing the spread
+  globally would hide 305 vendor items from Compass, 36 from Prudential and 1 from Elite, so the
+  hook was left alone and the page switched to the single-object form for Quad only. (bala)

package/knowledge/INDEX.md

@@ -18,11 +18,11 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 66 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 67 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)_ — 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)
+- **toga2-supply** (TOGa Supply) — 9 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)
 - **toga2-hub** (TOGa Hub) — 2 doc(s) → [2.0/apps/toga2-hub/INDEX.md](2.0/apps/toga2-hub/INDEX.md)

package/knowledge/clients/nychh/profile.md

@@ -15,7 +15,7 @@ project: _Underscore
 client: nychh
 type: profile
 status: active
-updated: 2026-08-24
+updated: 2026-08-26
 owners: ["jcardinal", "apeterson", "bala"]
 files:
   - dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql
@@ -60,6 +60,9 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   [NYCHH PO Number direction](./features/po-number-upstream-direction.md).
 
 ## Notes
+- **PO Number is upstream-sourced** (`PurchaseOrders_SalesOrders`), which is why the downstream
+  SO→PO route and the shared `_purchaseOrders` field came back empty. Details, and the
+  now-closed-on-`_beta` fix: [NYCHH PO Number](./features/po-number-upstream-direction.md).
 - 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
   pattern) and will show tracking once item-level tracking is backfilled.

package/knowledge/clients/quad/INDEX.md

@@ -3,5 +3,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 multi-currency item prices & vendor item costs](features/multi-currency-item-pricing.md) | 2.0 | Quad prices the **same item in several currencies** and costs the **same vendor item in the vendor's own currency**, so both listings must show a *set* of amoun | _underscore/Model/Quad/Item.php, _underscore/Model/Quad/VendorItem.php, toga2-supply/src/components/ui/CurrencyAmountLines.tsx, toga2-supply/src/pages/Items/api/itemsApi.ts, toga2-supply/src/pages/VendorItems/api/vendorItemsApi.ts, toga2-supply/src/pages/VendorItems/VendorItemsPage.tsx, dbchanges2/Client_Quad/2026-08-24 - Quad Multi Currency Item Pricing.sql, worker/crons/toga2/quad/Imports/import_items.php |
 | [Quad: PO + ASN email importer (import_po_and_asn.php)](features/po-asn-email-import.md) | 1.0 | Quad Graphics' supplier emails Purchase Order and Advance Shipping Notice CSVs into a monitored Microsoft 365 mailbox. | worker/crons/toga2/quad/import_po_and_asn.php |
 | [Quad Graphics](profile.md) | 2.0 | Quad Graphics is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Quad`. |  |

package/knowledge/clients/quad/features/multi-currency-item-pricing.md

@@ -0,0 +1,139 @@
+---
+title: Quad multi-currency item prices & vendor item costs
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: quad
+type: client-feature
+status: active
+updated: 2026-08-26
+owners: [bala]
+files:
+  - _underscore/Model/Quad/Item.php
+  - _underscore/Model/Quad/VendorItem.php
+  - toga2-supply/src/components/ui/CurrencyAmountLines.tsx
+  - toga2-supply/src/pages/Items/api/itemsApi.ts
+  - toga2-supply/src/pages/VendorItems/api/vendorItemsApi.ts
+  - toga2-supply/src/pages/VendorItems/VendorItemsPage.tsx
+  - dbchanges2/Client_Quad/2026-08-24 - Quad Multi Currency Item Pricing.sql
+  - worker/crons/toga2/quad/Imports/import_items.php
+related:
+  - ../profile.md
+  - ../../../2.0/apps/_underscore/features/calculated-sql-fields.md
+  - ../../../2.0/apps/api2/features/tableview-field-metadata.md
+  - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
+  - ../../../2.0/apps/toga2-supply/features/currency-amount-lines-editor.md
+  - ../../../2.0/apps/toga2-supply/features/table-data-additional-filters.md
+---
+
+## Summary
+
+Quad prices the **same item in several currencies** and costs the **same vendor item in the
+vendor's own currency**, so both listings must show a *set* of amounts rather than one number. Built
+2026-08-26: per-currency rows in `Client_Quad.ItemPrices` / `VendorItemCosts`, two calculated model
+fields that render them as text, a client-only column retype so the grid stops formatting them as
+dollars, and shared per-currency line editors in the item / vendor-item modals.
+
+## Data model
+
+- **`Client_Quad.ItemPrices`** — UNIQUE on `(itemId, priceTypeId, currencyId)`: one row per
+  currency an item is priced in.
+- **`Client_Quad.VendorItemCosts`** — UNIQUE on `(vendorItemId, priceTypeId, currencyId)`: one row
+  per currency a vendor item is costed in.
+
+### Quad's vendors are CURRENCY-LOCKED, one per country
+
+An item priced in N currencies has **exactly N vendor items** — one per regional vendor, each
+holding the cost in that vendor's own currency. Measured 2026-08-26: **76** items at 1 currency /
+1 vendor item, **37** at 2/2, **7** at 3/3.
+
+This is why the vendor-items grid **looks** broken and is not:
+
+- **Two `Vendors` rows share the name `TECNOLOGIA INFORMATICA TECINF SAS`** but are distinct
+  companies — number **COL-1** (Colombia, COP, 45 vendor items) and **PER-1** (Peru, PEN, 22). A
+  third row with no number and no vendor items is an unused stub.
+- Duplicate-looking rows are therefore **correct**. The instinct to merge them is wrong; the grid
+  needed a **Vendor #** column so the rows can be told apart.
+- **`catalogId = 1` maps exactly onto "has a cost"** for Quad: 179 vendor items in catalog 1 are
+  costed; the 402 in catalog 2 and 11 with `NULL` have none. That is what the vendor-items page
+  filters on (single-object filter form — see
+  [table-data request filters](../../../2.0/apps/toga2-supply/features/table-data-additional-filters.md)).
+
+## Backend — `_unitPrice` and `_unitCost`
+
+- **`_Model_Quad_Item::_unitPrice`** returns the persona-scoped **single amount** when a
+  `personaId` argument is supplied, and a **`GROUP_CONCAT` of `'CODE amount'` pairs across every
+  currency** when it is not. Previously it returned literal SQL `NULL` with no persona, which is
+  why the listing column was always empty.
+- **`_Model_Quad_VendorItem::_unitCost`** (new) does the same for costs.
+- **Both must be declared as plain `self::FIELD_SQL`.** With
+  `FIELDOPT_SQL_TYPE => FIELD_DECIMAL` the framework casts the value with `(float)`, so
+  `'PLN 5295.00'` becomes `0` and the API returns `_unitPrice: 0` — see
+  [FIELD_SQL calculated fields](../../../2.0/apps/_underscore/features/calculated-sql-fields.md).
+
+## Grid presentation — retyped for Quad only
+
+The Core fields are `CURRENCY`, which renders a dollar icon and number formatting that is wrong for
+multi-currency text. Quad registers `CustomRecordFields` rows **with the same field names** and
+`type = STRING`, and points its `TableViewFields` rows at `customRecordFieldId`:
+
+- `_unitPrice` — Core `RecordFields` **909** (`CURRENCY`) → Quad `STRING`
+- `_unitCost` — Core **906** (`CURRENCY`) → Quad `STRING`
+
+Core is shared with every other client and was left untouched. **No `AclCustomFieldPermissions` row
+was added** — the names are already granted through the Core fields, and an extra row would keep the
+columns readable after a revoke. Recipe and rationale:
+[TableView field/column metadata](../../../2.0/apps/api2/features/tableview-field-metadata.md#per-client-type-override).
+
+**Header labels do not come from the custom rows.** A `ClientCustomRecordFieldSettings` label row
+for a custom column is never read by the grid; labels must come from
+`Core.DefaultRecordFieldSettings` on the Core field (or `ClientRecordFieldSettings` on a real
+`RecordField`), with both context columns `NULL`.
+
+## Front end
+
+One shared editable component (`CurrencyAmountLines`, `useFieldArray`) plus a read-only
+`CurrencyAmountList`, wired into the item and vendor-item **create and edit** modals behind
+`localStorage` `hostName === 'QUAD'`. The save/diff rules (a currency change is a delete + create;
+all deletes before all creates; never a nested `PUT`) are generic and live in
+[per-currency amount lines](../../../2.0/apps/toga2-supply/features/currency-amount-lines-editor.md).
+
+## Vendor-items Add / Edit buttons were hidden (fixed)
+
+Both controls read `acl['vendor-items']['navigation-edit-on-vendor-items']` — `Core.AclActions`
+id **7** on record **19**. `Client_Quad` had an `AclActionPermissions` row for id **5**
+(`navigation-vendor-items`) only, so the page was reachable with no buttons. This was a **UI gate
+only**: record 19 already granted role 1 (held by every Quad user) full CRUD and the live page meta
+already reported `_CREATE`/`_UPDATE`/`_DELETE` true. Granted id 7 to Quad **role 7 (Global Admin)**,
+following Compass Canada (which grants 5 and 7 both to role 10; Compass grants 5 → roles 9,11 and
+7 → role 16). In prod all seven Quad Global Admins also hold role 6, so they already see the page.
+Mechanism: [ACL permission chain — action flags](../../../2.0/apps/_underscore/features/acl-permission-chain.md).
+
+## ⚠ Open blocker — Items cannot be created from the UI (as of 2026-08-26)
+
+In **Quad prod**, `Core` record **21** (`Items`) has **`allowCreate = 0` for every Supply role**:
+role 1 (Base, appId 1) and roles 7/8/9 (appId 5) are all 0, and only role **3** (API) may create.
+So `POST /items` **403s for a UI user** and the New Item form cannot work until someone grants it.
+
+Not affected: records **19** (vendor items), **117** (item prices) and **118** (vendor item costs)
+all grant role 1 full CRUD, so vendor-item creates and every price/cost edit are permissioned
+correctly.
+
+**Do not re-debug this as a code bug, and do not build a write-translation hook.** The Quad item
+import cron (`worker/crons/toga2/quad/Imports/import_items.php`) already writes one `/item-prices`
+and one `/vendor-item-costs` row **per currency**, so no `_unitPrice` write hook is needed — the
+import was never broken, only the UI was.
+
+## Change history
+
+- 2026-08-26 — First capture. Built Quad per-currency item prices and vendor item costs end to end:
+  `_Model_Quad_Item::_unitPrice` now returns a persona-scoped amount with a `personaId` and a
+  `GROUP_CONCAT` of `'CODE amount'` pairs without one (it previously returned SQL `NULL`, so the
+  column was always empty), new `_Model_Quad_VendorItem::_unitCost` does the same for costs, both
+  declared plain `FIELD_SQL` so the value is not `(float)`-zeroed. Retyped `_unitPrice` (Core 909)
+  and `_unitCost` (Core 906) from `CURRENCY` to `STRING` for `Client_Quad` only via same-named
+  `CustomRecordFields` rows + `TableViewFields.customRecordFieldId`. Granted `AclActions` id 7 to role
+  7 so the vendor-items Add/Edit buttons appear. Recorded the currency-locked vendor model (76 items
+  1/1, 37 2/2, 7 3/3; TECINF COL-1 vs PER-1 are different companies; `catalogId = 1` ≡ has a cost) and
+  the open blocker that record 21 `allowCreate = 0` for all Supply roles makes UI item creation 403.
+  (bala)

package/knowledge/clients/quad/profile.md

@@ -15,13 +15,14 @@ project: _Underscore
 client: quad
 type: profile
 status: active
-updated: 2026-08-25
+updated: 2026-08-26
 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
+  - ./features/multi-currency-item-pricing.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
@@ -103,4 +104,18 @@ Client-specific DB change-sets live in `dbchanges2/Client_Quad/`.
   `EmailTemplates` rows containing a hardcoded `togasupply` host, so unlike Compass there is no
   template-body sweep to do. **The new route is unverified** — see the gotcha in
   [Compass approval-decision flow](../compass-usa/features/approval-decision-flow.md).
+- **Multi-currency item pricing & vendor costs (2026-08-26).** Quad prices an item once per
+  currency and costs each vendor item in that vendor's own currency; vendors are **currency-locked,
+  one per country**, so an item priced in N currencies has exactly N vendor items. The listings show
+  concatenated `'CODE amount'` text from `_unitPrice` / `_unitCost`, with those columns retyped
+  `CURRENCY → STRING` for `Client_Quad` only. See
+  [Quad multi-currency item pricing](./features/multi-currency-item-pricing.md).
+- **BLOCKER (2026-08-26): UI item creation 403s in prod.** `Core` record 21 (`Items`) has
+  `allowCreate = 0` for every Supply role (role 1 appId 1, roles 7/8/9 appId 5); only role 3 (API)
+  may create, so `POST /items` fails for a UI user. Vendor items (19), item prices (117) and vendor
+  item costs (118) are permissioned correctly. Not a code bug — needs an ACL grant.
+- **Vendor-items Add/Edit buttons needed an action-flag grant (2026-08-26).** Both controls read
+  `acl['vendor-items']['navigation-edit-on-vendor-items']` (`Core.AclActions` id 7 on record 19);
+  Quad had id 5 only. Granted id 7 to role 7 (Global Admin). UI gate only — record 19 already
+  granted role 1 full CRUD.
 - This profile is a starting point; expand as more Quad-specific behavior is captured.

package/package.json

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