toga-ai 1.0.650 → 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)