toga-ai 1.0.725 → 1.0.727

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

@@ -4,7 +4,7 @@
 |-----|---------|-------|
 | [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, dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql, _underscore/Model/Core/Page.php, _underscore/Model/Core/Surface.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, dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql, dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.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, dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql, _underscore/Model/Core/Page.php, _underscore/Model/Core/Surface.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, dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql, dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.sql, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.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 |

package/knowledge/2.0/apps/_underscore/features/acl-permission-chain.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
-owners: ["jcardinal", "mhammontree", "tcox", "bala"]
+updated: 2026-09-01
+owners: ["jcardinal", "mhammontree", "tcox", "bala", "apeterson"]
 files:
   - api2/Component/Api/V2/V2.php
   - dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql
@@ -21,6 +21,7 @@ files:
   - dbchanges2/Client_Quad/2026-08-24 - Quad Multi Currency Item Pricing.sql
   - dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql
   - dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.sql
+  - dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql
 ---
 
 ## Summary
@@ -127,8 +128,46 @@ identical in every environment (the platform's only sanctioned hardcoded ids —
 next free id differs per environment (a new field took 2483 in production and 2766 in
 dev-sandbox), so a row you are creating right now may need a per-environment literal.**
 
-**Known-broken existing files (same root cause):** `Client_Rate/2026-07-23a` and
-`Client/2026-07-16c`. A clean local run is never proof either worked.
+**Known-broken existing files (same root cause).** A full sweep of `dbchanges2` on **2026-09-01**
+found **12** `Client/` files doing a real cross-cluster read (`FROM`/`JOIN Core.*`). All of them are
+**ACL or surface-grant** migrations, and all fall in a **2026-06-25 → 2026-07-23** window —
+`Core/` is clean, so the leak is one-directional:
+
+| File (`dbchanges2/Client/`) |
+|---|
+| `2026-07-22c - TrackingNumberMeasureIdsFieldPermission` (10 `Core.` refs) |
+| `2026-07-16b - TrackingNumberSignatureTypeFieldPermission` |
+| `2026-07-16c - AddressValidateScriptAcl` |
+| `2026-07-23a - EntitlementServiceAddressIdFieldPermission` |
+| `2026-07-17 - ItemsisFulfillable` |
+| `2026-07-10b - ItemFulfillmentReturnAddressIdFieldPermission` |
+| `2026-07-10c - GenerateReturnLabelScriptAcl` |
+| `2026-07-02a - TrackingNumberReprintScriptAcl` |
+| `2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission` |
+| `2026-06-30a - SurfaceMetaGroupAcl` |
+| `2026-06-29c - SurfaceRecordScriptAcl` |
+| `2026-06-25c - SurfaceClientAcl` |
+
+(plus `Client_Rate/2026-07-23a`, previously known.) **A clean local run is never proof any of them
+worked** — locally the schema literally named `Core` is the **1.0** database, so the subselect
+resolves against the wrong schema instead of failing.
+
+**Their failure mode is silent, and it is worth stating precisely** because it is why nobody caught
+this for two months: `SET @x = (SELECT … FROM Core.X)` yields **NULL**, the `IS NOT NULL` guard then
+suppresses the `INSERT`, and **the file reports success having granted nothing**. No error, no
+warning, zero rows.
+
+**Confirmed live instance:** `Client_Adyen` has `2026-07-22c`'s mirror sibling grant but **none of
+that file's three measure-id fields** — exactly the shape this bug produces.
+
+Verified on production 2026-09-01: both `reader1.client.database.togahub.com` and
+`writer.client.database.togahub.com` host **only `Client_*` databases — there is no `Core` there
+at all**, so a `Core.X` reference from a `Client/` file cannot resolve under any circumstances.
+
+**New occurrences are now blocked** by the `dbchanges2-cluster-isolation` PreToolUse hook
+(`.claude/hooks/toga/dbchanges2-cluster-isolation.js`), which inspects every `Write`/`Edit`.
+The 12 above pre-date it and are a **remediation backlog**, not a closed issue — each needs its
+`Core` subselect swapped for a hardcoded `Core.RecordFields` id literal and then re-running.
 
 ### Standard field vs. custom (`c_`) field — TWO different permission tables
 
@@ -191,6 +230,33 @@ first (see
   granting access therefore goes in `dbchanges2/Client/` (or a specific `Client_<Name>/`) so it
   runs against every client DB.
 
+### ⚠ Read `aclDatabase` FIRST — querying the wrong database gives a confident, meaningless answer
+
+This is the step that is easiest to skip and the most expensive to skip, because **both databases
+have an `AclFieldPermissions` table**. Query the wrong one and you get rows back, draw a conclusion,
+and never learn it was about a different record. Verified the hard way 2026-09-01: `Core` was
+checked for `purchase-order-items` (`Records.id = 18`), which is **`aclDatabase = 'CLIENT'`** — so
+Core's rows are **never consulted for that record** and the whole investigation went down a wrong
+path on the strength of them.
+
+**Recipe — "a field returns 0/null but the data is there":**
+
+1. **Establish the ACL database before anything else:**
+   ```sql
+   SELECT id, route, aclDatabase FROM Core.Records WHERE route = '<route>';
+   ```
+2. **Query `AclFieldPermissions` in THAT database** — `Core` if `CORE`, `Client_<Tenant>` if
+   `CLIENT`. Rows in the other one are noise.
+3. **Compare a field that WORKS against the broken one, side by side.** A role row present on one
+   and absent on the other is conclusive; a raw list of grants for the broken field alone is not,
+   because you have no baseline for what "granted" looks like on that record.
+
+> **⚠ Before spending any time on steps 1–3, check whether ACL can even be the cause.** If the
+> field is **`_`-prefixed and requested through an explicit `fields=` list**, `AclFieldPermissions`
+> is **bypassed entirely** and no grant you add or remove will change the result — see
+> [V2 REST query contract → ACL behavior](../../api2/features/v2-rest-query-contract.md). Confirm
+> the request shape first; it eliminates the entire ACL chain in one step.
+
 **Role ids differ per client DB**, so never hardcode a `roleId` in a `CLIENT` ACL migration —
 resolve it with a subselect, e.g. the Base role:
 
@@ -423,6 +489,46 @@ and **succeeds with 0 inserted and no error**. Always confirm the sibling has ro
 `shippingMethodId` (338), `measures.slug` (723), `containsBattery` (962), `shipToAddressId` (991).
 **Do NOT mirror `needsReturnLabel`** — its grants are absent in some clients.
 
+### ⚠ But when you know the TARGET role, grant it EXPLICITLY — mirroring is the riskier option
+
+The mirror practice above answers *"which roles read this kind of field?"* when you genuinely do not
+know. **When you already know the role you need, name it — do not mirror.** Mirroring looks tidier
+and reads as the house style (`Client/2026-07-22c` is the precedent), but it copies whatever the
+sibling happens to have in each tenant, and that set is **not uniform**. Two live failures from one
+2026-09-01 survey of the `PurchaseOrderItems._qty*` fields:
+
+- **Mirroring over-grants.** `Client_Compass` grants `quantity` to **role 4 (Public)**. A migration
+  mirroring `quantity` would have handed the **Public** role read access to eight derived inventory
+  quantities across that tenant — a real widening, applied silently, in a file whose stated purpose
+  was to grant the API role.
+- **Mirroring under-grants.** `Client_Imhouston` has **no `quantity` grant at all**, so the same
+  mirror inserts **zero rows** there and the field stays broken — the silent-no-op failure already
+  described above.
+
+**Rule: resolve the role BY NAME (`(SELECT id FROM Roles WHERE name = 'API')`) and grant it
+explicitly.** You keep the per-tenant role-id independence that mirroring was bought for, without
+inheriting a per-tenant role *set* you never inspected. Reserve mirroring for the case where the
+reader role is genuinely unknown — and when you do mirror, dry-run it per tenant and read the role
+ids it would actually insert.
+
+### Fleet reality check: a template mis-seed means "most tenants" is not "correct"
+
+The same survey (36 production client databases, 2026-09-01) on the eight
+`PurchaseOrderItems._qty*` fields:
+
+| Grant state | Tenants |
+|---|---|
+| all eight granted to **role 1 (Base)**, **none to role 3 (API)** | **31** |
+| **no `_qty*` grants at all** | 4 — Compass, Imhouston, Mcgrawhill, Tdsynnex |
+| roles 1 **and** 3 (correct) | 1 — Prudential |
+| role 3 (correct for API use) | 1 — Northwell |
+
+**A 31-of-36 majority was the WRONG state**, not the baseline — this is a template-level mis-seed
+propagated by the blank-client DDL, so every tenant provisioned from it inherits the same gap.
+Practical consequence: **never infer the intended grant from what most tenants have.** Derive it
+from which role actually reads the field, then check whether the majority agrees; when it does not,
+suspect the template rather than the two outliers.
+
 Reconfirmed 2026-08-03 (TRUE-80494): `measures.measureType` had **zero** grant rows in dev-sandbox
 `Client_Growrk`, so it was omitted from `GET /v2/measures`; the frontend's strict
 `m.measureType === "LENGTH"` split then produced empty arrays and **both unit dropdowns rendered
@@ -492,6 +598,26 @@ 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-09-01** — Four additions from a `PurchaseOrderItems._qty*` grant investigation.
+  (1) **Read `Core.Records.aclDatabase` FIRST** — both databases carry an `AclFieldPermissions`
+  table, so checking Core for a `CLIENT`-acl record (here `purchase-order-items`, record 18) returns
+  rows and a confident wrong answer; added the compare-a-working-field diagnostic recipe, gated on
+  first confirming ACL can even apply (an `_`-prefixed field in an explicit `fields=` list **bypasses
+  `AclFieldPermissions` entirely** — new section in
+  [v2-rest-query-contract](../../api2/features/v2-rest-query-contract.md)).
+  (2) **Grant a KNOWN target role explicitly rather than mirroring a sibling** — mirroring `quantity`
+  would have granted **role 4 (Public)** eight derived inventory quantities on `Client_Compass` and
+  inserted **nothing** on `Client_Imhouston` (no `quantity` grant there); resolve by role *name*
+  instead. This qualifies, and partly reverses, the house mirror precedent `Client/2026-07-22c`.
+  (3) **A 31-of-36 majority can be the wrong state** — 31 prod tenants grant the `_qty*` fields to
+  role 1 and none to role 3; only Prudential and Northwell are correct. Template-level mis-seed, so
+  never infer the intended grant from the majority.
+  (4) **Expanded the known-broken cross-cluster file list from 2 to 12** (full `dbchanges2` sweep;
+  all `Client/` ACL/surface grants in a 2026-06-25 → 2026-07-23 window, `Core/` clean), stated the
+  silent failure mechanism (`SET @x = (SELECT … FROM Core.X)` → NULL → guard suppresses the INSERT →
+  reports success), confirmed `Client_Adyen` as a live instance, verified on prod that the client
+  cluster hosts no `Core` at all, and noted the new `dbchanges2-cluster-isolation` PreToolUse hook
+  blocks new ones while these 12 remain a remediation backlog. (apeterson)
 - **2026-08-29** — Two more worked examples of the **standard-field write grant via hardcoded
   `Core.RecordFields` id literal** (the cross-cluster caveat — a `Client_*`→`Core` JOIN is refused on the
   prod client cluster), each cloning a working sibling: `ItemReceipts.transferOrderId` (Core RF **2153**,

package/knowledge/2.0/apps/api2/features/v2-rest-query-contract.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-30
+updated: 2026-09-01
 owners: [tcox, bala, apeterson, jcardinal]
 files:
   - api2/Component/Api/V2/V2.php
@@ -259,6 +259,46 @@ where=(field:op:value,LOGIC,field:op:value,(nested,OR,nested))
     list, **and the permitted data still populated**.
   - **Recommendation: always send an explicit `fields=` list.** Silent omission is how a
     consumer ends up "working" against data it never actually received.
+  - **⚠ That recommendation holds for PLAIN fields only — an `_`-prefixed field named in
+    `fields=` is never ACL-checked at all.** See the next section.
+
+### ⚠ An explicitly-requested `_`-prefixed field BYPASSES `AclFieldPermissions` entirely
+
+This is the exception to everything above, and it inverts the usual debugging instinct: for an
+underscore-prefixed field, **adding an `AclFieldPermissions` grant changes nothing** about an
+explicit `fields=` request. Verified 2026-09-01 on `purchase-order-items._qty*`.
+
+`processRoutePairs()` classifies each entry of an explicit `fields=` list in a fixed order, and the
+ACL branch is **not first**:
+
+| `V2.php` | branch | ACL checked? |
+|---|---|---|
+| **:3338** | `$modelFieldConfig[$f]['type'] == _Model::FIELD_SQL` → **calculated field** | **no** |
+| **:3353** | field starts with `_` but is not `FIELD_SQL` → reclassified as an **aggregate function** (`'function' => substr($field, 1)`) | **no** |
+| **:3375–3381** | plain field with no grant → *"not permitted access, unauthorized"* → **`EZ-2`** | yes |
+
+So `fields=_qtyAvailable` resolves at **:3338** and the request never reaches the ACL branch. The
+ACL gate for calculated fields lives at **:7216** in `getFullModelData()` — which is the
+**no-explicit-`fields=`** path only.
+
+**The two practical consequences:**
+
+1. **Granting `AclFieldPermissions` does not change the result of an explicit `fields=` request for
+   a calculated field.** If a `_qty*` field returns `0` with the grant added and with it removed,
+   the ACL was never the variable — stop testing grants and go look at the SQL the field emits
+   (and at *which model class* is emitting it — see the NYCHH case linked below).
+   The grant is still worth having: it is load-bearing on the `getFullModelData()` path.
+2. **Plain fields fail LOUDLY, calculated fields fail SILENTLY.** An ungranted plain field is a
+   `EZ-2` 403 you cannot miss. An ungranted `_`-prefixed field is quietly turned into an aggregate
+   function, and — because these fields typically carry
+   `FIELDOPT_SQL_TYPE => FIELD_DECIMAL` — the serializer still emits the key and it renders as
+   **`0`**. It reads as a broken calculation, not as a permission problem, which is exactly the
+   wrong place to start looking. (The `FIELD_DECIMAL` cast is documented on
+   [FIELD_SQL calculated fields](../../_underscore/features/calculated-sql-fields.md).)
+
+**Corollary for the `fields=`-forces-`EZ-2` diagnostic above:** re-requesting with an explicit
+`fields=` list to smoke out a denied field **only works on plain columns**. It will never produce an
+`EZ-2` for a `_`-prefixed field, so a silent `0` is not evidence that the grant exists.
 - **`EZ-1` vs `EZ-2` for a consumer:** `EZ-1` = record-level block (`data.<route>` is `null`) —
   hard blocked, nothing usable. `EZ-2` = field-level — on a **LIST** it is
   *degraded-but-usable*; on a **by-uuid READ** it is **fatal**.
@@ -296,7 +336,14 @@ where=(field:op:value,LOGIC,field:op:value,(nested,OR,nested))
 - **A 500 (`EO-1`) on a filter ⇒ suspect a `where` reference to an unjoined table.**
 - **`gte`/`lte` silently are not operators** — use `ge`/`le`.
 - **Do not trust a 200 with missing fields.** Without an explicit `fields=` list, ACL removal is
-  invisible; re-request with `fields=` to force `EZ-2` and see the denied list.
+  invisible; re-request with `fields=` to force `EZ-2` and see the denied list. **⚠ Plain columns
+  only** — an `_`-prefixed field named in `fields=` is never ACL-checked and returns `0`, not
+  `EZ-2` (see the ACL section).
+- **⚠ A calculated field returning `0` is almost never an ACL problem.** Eliminate ACL in one
+  step (it is bypassed on the explicit-`fields=` path), then check **which model class** supplies
+  the expression — a `_Model_<Client>_X` override on the *deployed* `_underscore` branch can
+  replace the base SQL with something that legitimately evaluates to `0`. Worked example:
+  [NYCHH transfer-order inventory quantities](../../../clients/nychh/features/transfer-order-inventory-quantities.md).
 - **⚠ A PUT response ECHO can omit a field that DID persist — verify against the DB, not the echo.**
   A `PUT /v2/inventory-adjustments/{uuid}` with `{"itemFulfillment":{"uuid":…}}` returned **200 with
   an empty `messages[]`** and an echo that did **not** contain `itemFulfillment`, yet the FK column
@@ -306,6 +353,16 @@ where=(field:op:value,LOGIC,field:op:value,(nested,OR,nested))
   [V2 request logging](request-logging.md).
 
 ## Change history
+- 2026-09-01 — **Recorded the biggest exception to this doc's own "always send an explicit `fields=`
+  list" advice: an `_`-prefixed field named in `fields=` is NEVER ACL-checked.** `V2.php:3338`
+  classifies a `FIELD_SQL` field as calculated *before* the ACL branch at `:3353`, and `:3353` then
+  reclassifies any other `_`-prefixed field as an **aggregate function** rather than denying it —
+  only plain fields reach the `EZ-2` branch at `:3375-3381`. The ACL gate for calculated fields is
+  at `:7216`, on the **no-explicit-`fields=`** path. Two consequences: adding an
+  `AclFieldPermissions` grant cannot change the result of an explicit `fields=_qtyX` request, and
+  ungranted calculated fields fail **silently as `0`** (the `FIELDOPT_SQL_TYPE => FIELD_DECIMAL`
+  cast still emits the key) while plain fields fail loudly. Found while a `_qty*` field returned 0
+  and a grant migration was written against the wrong theory. (apeterson)
 - 2026-08-29 — Recorded two response-shape facts from the NYCHH inventory-adjustment REST work: **a
   non-null FK object one hop past the max `depth` is silently omitted** (a null sibling FK still
   renders, so it reads as "null" not "missing") — `GET /item-fulfillment-items` at `depth:2` dropped

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

@@ -3,7 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Database Changes (dbchanges2) Repository Architecture](architecture.md) | `dbchanges2` is the **schema-migration / SQL change-set repository** for the entire 2.0 platform. | Core/, Client/, Client_<Tenant>/, Logs/, Logs_Client/, _modules/ |
-| [Re-runnable additive migrations (uuid4 in SQL, INSERT guards, the DISTINCT trap, conditional ALTERs)](features/rerunnable-additive-inserts.md) | Most `dbchanges2` files are **additive data grants** run by hand against production, often more than once (once per environment, or twice because someone was no | dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql, dbchanges2/Core/2026-08-27a - Insert - Netsuite Location SyncAll CronJob.sql |
+| [Re-runnable additive migrations (uuid4 in SQL, INSERT guards, the DISTINCT trap, conditional ALTERs)](features/rerunnable-additive-inserts.md) | Most `dbchanges2` files are **additive data grants** run by hand against production, often more than once (once per environment, or twice because someone was no | dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql, dbchanges2/Core/2026-08-27a - Insert - Netsuite Location SyncAll CronJob.sql, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql |
 | [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Core/2026-08-31a - SalesOrderDenialDetailsSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-31a - SalesOrderDenialDetailsReadOnlyRules.sql, toga25-supply/db-migrations/PLAYBOOK.md, toga25-supply/db-migrations/SURFACE-FEATURE-RUNBOOK.md, dbchanges2/Client_Compass/, dbchanges2/Client_CompassCanada/, dbchanges2/Client_Quad/, dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql, dbchanges2/Core/2026-08-24b - SalesOrderStatusFilterSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_CompassCanada/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Quad/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Nychh/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Core/2026-08-21 - SalesOrderDecisionSurfacesReseed.sql, dbchanges2/Core/2026-08-24 - RestoreApproveDenyRowActionsVisibility.sql, dbchanges2/Client_Quad/2026-08-24 - ProdPortApprovePoNumberEnabledRule.sql, dbchanges2/Client_Quad/2026-07-21b - ApproveDisabledTooltipPoNumber.sql, dbchanges2/Client_Quad/2026-08-21 - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_CompassCanada/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Core/2026-07-20a - Update - HideAdminNotesSectionByDefault.sql, dbchanges2/Core/2026-07-20b - Update - NotesSectionFieldElements.sql, dbchanges2/Client_Compass/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_Compass/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_Quad/2026-07-20a - NotesSectionFieldsOverride.sql, dbchanges2/Core/2026-07-20c - Update - VendorItemsToggleSurfaceSeed.sql, dbchanges2/Client_Compass/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Core/2026-07-20e - RestoreApproveDenyRowActions.sql, dbchanges2/Client_Compass/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Core/2026-07-17 - README - RUN ORDER.md, dbchanges2/Client_Compass/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Compass/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_CompassCanada/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_Quad/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Quad/2026-07-21b - SalesOrderApproveDisabledTooltipTranslation.sql, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Core/2026-07-23a - PoNumberDetailFieldValueKey.sql, dbchanges2/Core/2026-07-29a - SalesOrderApprovalDetailsSurfaceSeed.sql, dbchanges2/Core/2026-08-05b - ApprovalDetailsShippingMethodConcatCharge.sql, dbchanges2/Core/2026-08-14a - NoteBadgesVocabularySurface.sql, dbchanges2/Client/2026-08-14a - NoteBadgeThemeTokens.sql, dbchanges2/Client/2026-08-14b - NoteBadgeUserColorFix.sql, dbchanges2/Client_Compass/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Client_CompassCanada/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Core/2026-08-26a - ServiceRequestRecordHeaderSurfaceSeed.sql, dbchanges2/Core/2026-08-26b - ServiceRequestDetailsSurfaceSeed.sql, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql |
 | [2.0 New-Client Onboarding (manual process)](workflows/client-onboarding.md) | > **A local browser wizard now automates this.** Steps 2–9 below (create DBs, generate Core/API > inserts, append to `Clients_Db.txt`) — plus the dbchanges2 bla | Client/, Client_<Tenant>/, Core/, Logs_Client/ |
 | [Auditing a client DB that drifted from its models (partially applied module migration)](workflows/client-schema-drift-audit.md) | A recurring 2.0 failure mode: **one client's database drifts from what the PHP models declare**, usually because a `_modules/<module>/` migration was applied to | dbchanges2/Client_Growrk/2026-05-28.sql, dbchanges2/Client_Growrk/2026-08-10c - GrowrkServiceRequestCustomFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10d - GrowrkServiceRequestTypeAndDispositionSeeds.sql, dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Growrk/2026-08-10 - GrowrkUnitInventoryFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10b - GrowrkUnitItemDescriptionAcl.sql, dbchanges2/Client_Growrk/_modules.txt |

package/knowledge/2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md

@@ -6,15 +6,17 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-08-31
+updated: 2026-09-01
 owners: [bala, kyalamarthi, apeterson]
 files:
   - dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql
   - dbchanges2/Core/2026-08-27a - Insert - Netsuite Location SyncAll CronJob.sql
+  - dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql
 related:
   - ../architecture.md
   - ../../worker2/features/netsuite-salesorder-open-orders-sync.md
   - ../../_underscore/features/acl-permission-chain.md
+  - ../../_underscore/features/calculated-sql-fields.md
   - ../../_underscore/features/tracking-number-bridges.md
   - ../../../../clients/compass-usa/workflows/granting-persona-bundle-access.md
   - ../../../../clients/compass-usa/workflows/granting-navigation-access.md
@@ -49,6 +51,36 @@ and `SUBSTRING('89ab', …)` picks the variant nibble. Verified working on prod
 that is *not* v4-shaped (older migrations concatenated `RANDOM_BYTES` without the version/variant
 nibbles). They are fine and must not be "fixed" — but do not use them as the template for new SQL.
 
+### ⚠ In a FAN-OUT grant migration, use HARDCODED uuid literals — generated uuids make rollback unsafe
+
+The generator above is right for a normal additive insert. It is **wrong for a `Client/` fan-out
+that grants a permission across every tenant**, because you cannot write a safe rollback for rows
+whose uuids you do not know.
+
+The tempting rollback is a natural key:
+
+```sql
+-- DANGEROUS in a fan-out: deletes grants this file never created
+DELETE FROM AclFieldPermissions WHERE recordFieldId IN (…) AND roleId = (SELECT id FROM Roles WHERE name = 'API');
+```
+
+That also removes **pre-existing** grants held by the tenants that were already correct. Concrete
+case (2026-09-01, the `PurchaseOrderItems._qty*` role-3 grant): Prudential and Northwell already had
+these rows, so a key-based rollback would have **revoked working production permissions** on two
+tenants as collateral for undoing 34 others.
+
+**Instead, hardcode one v4 uuid literal per row in the file.** The rollback is then exact:
+
+```sql
+DELETE FROM AclFieldPermissions WHERE uuid IN ('<literal-1>', …, '<literal-8>');
+```
+
+It can only ever match rows this file inserted. **Reusing the same literal across tenants is valid**
+— `uuid` is unique *per table per database*, and each tenant is a separate database, so one literal
+per (row × file) is enough for the whole fan-out. Keep the `NOT EXISTS` guard on the real unique key
+(here `(recordFieldId, roleId)`) so re-running is still a no-op on tenants that already have the
+grant; the literal governs only deletion.
+
 ### ⚠ `DISTINCT` cannot dedupe a row that carries a random uuid
 
 This is the silent one. In an `INSERT … SELECT`, putting the uuid expression inside a
@@ -235,8 +267,29 @@ concluding a migration is production-safe.
   file: separate production clusters mean a `Core.` reference is unrunnable in prod even though it
   works locally. Hardcode `Core.Records` / `Core.RecordFields` ids as literals — see
   [dbchanges2 architecture](../architecture.md).
+- **⚠ Read the sibling migration's `INSERT` HEADER — never infer the column list from its `VALUES`
+  row.** Copying a neighbouring file is the normal way to start a migration, and matching the
+  *shape* of its values tuple (right arity, plausible-looking types) produces a file that looks
+  correct and fails on execution. Verified 2026-09-01: `Core.Messages` is
+  **`(id, uuid, dtCreated, messageKey, name, defaultValue)`** — a guess of `slug` / `message`
+  (inferred from a sibling's values row) died on `Unknown column 'slug'`. When in doubt,
+  `SHOW COLUMNS FROM <Table>` costs one round-trip.
+- **`Core.RecordFields` has NO `sql` column.** A calculated field's SQL is **not** stored in
+  metadata — it lives in the `_underscore` model as a `FIELD_SQL` static method. Do not go looking
+  for a migration to change a calculated field's expression; there is none. See
+  [FIELD_SQL calculated fields](../../_underscore/features/calculated-sql-fields.md).
 
 ## Change history
+- 2026-09-01 — Added the **fan-out rollback rule**: a `Client/` grant migration that fans out across
+  every tenant must use **hardcoded v4 uuid literals**, not the generator, so its rollback
+  (`DELETE … WHERE uuid IN (…)`) can only touch rows that file created. A natural-key rollback on
+  `(recordFieldId, roleId)` would have revoked **pre-existing production grants** on Prudential and
+  Northwell while undoing the `PurchaseOrderItems._qty*` role-3 fan-out. Reusing one literal per row
+  across tenants is valid (uuid is unique per table per database). Also recorded two schema gotchas:
+  **read a sibling's `INSERT` header, never infer columns from its `VALUES` row** (`Core.Messages` is
+  `(id, uuid, dtCreated, messageKey, name, defaultValue)` — a guessed `slug` failed with *Unknown
+  column*), and **`Core.RecordFields` has no `sql` column** — calculated-field SQL lives in the
+  model, not in metadata. (apeterson)
 - 2026-08-28 — Added **conditional (re-runnable) ALTERs**: MySQL 8 has no
   `ADD COLUMN IF NOT EXISTS`, so a `Client/` all-tenant file must gate each `ALTER` on
   `information_schema` (with `TABLE_SCHEMA = DATABASE()` for cluster safety) and run it through

package/knowledge/2.0/apps/dbchanges2/workflows/targeting-the-right-database.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: workflow
 status: active
-updated: 2026-08-31
+updated: 2026-09-01
 owners: [apeterson]
 files:
   - api2/Config/production.ini
@@ -85,11 +85,24 @@ Delete the file when you are done.
   `Table 'Client_Nychh.Messages' doesn't exist`, which names a missing table rather than the real
   mistake. If you see "table doesn't exist" for a table you know is in Core, check which schema you
   piped the file into before you touch the SQL.
+- 🚨 **A `Client/` fan-out hits EVERY `Client_*` schema on the cluster — including dated BACKUP
+  databases.** The production client cluster carries copies that are not tenants. Found
+  2026-09-01: **`Client_Compass_20260831_120000`**, a dated backup of `Client_Compass`, sitting
+  alongside the live schemas. Any "run this against every `Client_*` database" loop picks it up,
+  which at best wastes a run and at worst mutates a snapshot someone is holding for a restore.
+  **Before a fan-out, list the target schemas and eyeball them** —
+  `SHOW DATABASES LIKE 'Client\_%'` — and exclude anything matching a `_YYYYMMDD_HHMMSS` suffix or
+  otherwise absent from `Core.Clients`. Do not assume the tenant list and the schema list agree.
 - **The repo is evidence of intent, never of what an environment contains.** Confirming a file ran
   is its own procedure — see
   [Verifying whether a migration actually ran](./verifying-a-migration-ran.md).
 
 ## Change history
+- 2026-09-01 — Added the **backup-database hazard for `Client/` fan-outs**: the production client
+  cluster hosts dated snapshots alongside live tenants (`Client_Compass_20260831_120000`, found
+  during a 36-database ACL survey), and a naive "every `Client_*` schema" loop will run against
+  them. List and filter the target schemas (`SHOW DATABASES LIKE 'Client\_%'`, drop
+  `_YYYYMMDD_HHMMSS` suffixes / anything not in `Core.Clients`) before fanning out. (apeterson)
 - 2026-08-31 — Initial. Captured after a dump taken from `127.0.0.1` was restored onto sandbox-client
   `Client_Nychh` believing it was production (the tell: sandbox matched local exactly). Records the
   verify-by-differing-row-count check, the `--single-transaction` snapshot-drift caveat, the

package/knowledge/2.0/apps/toga-blox/features/api-client.md

@@ -6,7 +6,7 @@ project: TOGa Blox
 client: shared
 type: feature
 status: active
-updated: 2026-08-27
+updated: 2026-09-01
 owners: [apeterson, tcox]
 files:
   - toga-blox/src/reactQuery/queryHelpers.ts
@@ -118,6 +118,25 @@ Filterable`, `hyperlinkField`, `imageUrlField`, `sticky`, `precision`, …), `Da
   paren pair so the group re-wrap doesn't double-wrap. Any raw pre-formatted where clause was
   100% broken before this. If you add a new raw-string clause path, route it through this string
   branch — do **not** feed a raw clause into an object-expecting serializer.
+- **⚠ Every `where` VALUE must be a STRING — a number throws inside `buildUrl` and NO request is
+  ever sent.** `urlEncode(input: string)` calls `input.replace()`, so a numeric value raises
+  `input.replace is not a function` **synchronously** inside `assembleOptions` → `buildUrl` →
+  `queryFn`. React Query reports it as a query error, and because the throw happens *before* the
+  fetch, **DevTools shows no network activity at all** — the symptom is an empty list/dropdown with
+  a completely clean network tab, which reads as a backend or ACL problem and is neither.
+
+  ```ts
+  // WRONG — throws in buildUrl, no HTTP request
+  where: { "Locations.isActive": { "=": 1 } }
+
+  // CORRECT
+  where: { "Locations.isActive": { "=": "1" } }
+  ```
+
+  TypeScript does not catch it today. This is the **second** shape-assumption failure in
+  `reactQuery/queryHelpers.ts` (the raw-string `apiWhereClause` bug above is the first): the
+  serializer trusts its input's type and fails loudly only at the very end of the chain. Verified
+  2026-09-01 in `toga25-supply` (`useTargetLocationOptions.ts`, `useTransferSourceLocation.ts`).
 - **⚠ AUTHORING DEFECT — `handleClientAuthentication(uuid)` collides by name with app-local SSO
   helpers and is not interchangeable with them.** blox's version `POST`s
   `/auth/encrypted-user-uuid` with an **empty payload** (`{client:"",user:""}`), writes
@@ -152,6 +171,12 @@ Filterable`, `hyperlinkField`, `imageUrlField`, `sticky`, `precision`, …), `Da
   thread, not a settled finding.
 
 ## Change history
+- 2026-09-01 — Recorded that **`where` values must be STRINGS**: `urlEncode` calls
+  `input.replace()`, so a numeric value throws `input.replace is not a function` synchronously in
+  `buildUrl`/`queryFn` and **no HTTP request is made at all** — an empty dropdown with a clean
+  network tab, easily misread as a backend/ACL fault. Second shape-assumption failure in
+  `reactQuery/queryHelpers.ts` after the 2026-08-17 raw-string clause bug; TypeScript does not catch
+  it. Hit in `toga25-supply`'s Create Transfer Order modal. (apeterson)
 - 2026-08-27 — Recorded three blox **authoring defects** surfaced while debugging toga25-supply SSO:
   (1) `handleClientAuthentication` collides by name with app-local SSO helpers and returns a
   `/users` payload with no `singleSignOnServiceUrl`; (2) `fetchPublicToken` persists the public

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

@@ -14,7 +14,7 @@
 | [SSO redirect & public-vs-user session gating (useAuthenticationFlow)](features/sso-redirect-and-session-gating.md) | How 2.5 Supply decides, on every navigation, whether an anonymous visitor should be bounced to their client's SSO IdP instead of the local `/login` form. | toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/src/routes.tsx, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/api/api.ts |
 | [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/App.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/DenialBanner.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/SalesOrderRecordModal.module.css, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/SalesOrderApprovalModalsLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/RecordApprovalModalLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/view/ApprovalTimelineView.tsx, toga25-supply/src/layout/RecordApprovalModal/ApprovalModal.module.css, toga25-supply/src/utils/formatDateTime.ts, toga25-supply/src/utils/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/layout/RecordApprovalModal/, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/surface/applyColSpan.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/ServiceRequestRecordModalLayout.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/view/ServiceRequestsView.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/useServiceRequestRecordModalLayoutModel.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/AdminNotesSection.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getAdminNotes.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderVip.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/surface/SurfaceHeader.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
 | [Talos Integration (AppLayout host + adapter wiring)](features/talos-integration.md) | toga25-supply is the first host of the shared blox [Talos assistant](../../toga-blox/features/talos-assistant.md). | toga25-supply/src/layout/AppLayout/AppLayout.tsx, toga25-supply/src/components/Header/Header.tsx, toga25-supply/src/components/Header/Header.module.css, toga25-supply/src/index.css, toga25-supply/src/assets/talos-owl.png |
-| [Transfer Orders page (TableView → Core surfaces → React page + record modal)](features/transfer-orders-page.md) | The Transfer Orders screen — list + read-only record modal — built end to end on 2026-08-28 from a Claude Design prototype. | toga25-supply/src/pages/TransferOrders/TransferOrders.tsx, toga25-supply/src/pages/TransferOrders/hooks/useTransferOrdersTableState.ts, toga25-supply/src/pages/TransferOrders/viewModel/useTransferOrdersPageViewModel.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrdersTableLayout/TransferOrdersTableLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/TransferOrderRecordModalLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/hooks/useTransferOrderRecord.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/viewModel/useTransferOrderRecordModalLayoutModel.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/view/TransferOrderRecordView.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/CreateTransferOrderModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/index.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTransferableItemRows.ts, toga25-supply/src/surface/useColumnVisibilityModalConfig.ts, toga25-supply/src/routes.tsx, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql |
+| [Transfer Orders page (TableView → Core surfaces → React page + record modal)](features/transfer-orders-page.md) | The Transfer Orders screen — list + read-only record modal — built end to end on 2026-08-28 from a Claude Design prototype. | toga25-supply/src/pages/TransferOrders/TransferOrders.tsx, toga25-supply/src/pages/TransferOrders/hooks/useTransferOrdersTableState.ts, toga25-supply/src/pages/TransferOrders/viewModel/useTransferOrdersPageViewModel.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrdersTableLayout/TransferOrdersTableLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/TransferOrderRecordModalLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/hooks/useTransferOrderRecord.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/viewModel/useTransferOrderRecordModalLayoutModel.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/view/TransferOrderRecordView.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/CreateTransferOrderModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/index.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/usePurchaseOrderItemRows.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTargetLocationOptions.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTransferSourceLocation.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useLocationContacts.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateLocationContact.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/AddContactModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/TransferNotesField.tsx, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql, toga25-supply/src/surface/useColumnVisibilityModalConfig.ts, toga25-supply/src/routes.tsx, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql |
 | [AWS Amplify Multi-Environment Deployment](workflows/amplify-deployment.md) | How `toga25-supply` deploys to **all** of its environments on AWS Amplify from a **single shared `amplify.yml`**. | toga25-supply/amplify.yml, toga25-supply/src/api/api.ts, toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/vite.config.ts, toga25-supply/package.json, toga25-supply/.env.development |
 | [Cypress Testing Harness (component + e2e)](workflows/cypress-testing.md) | The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch (`cypress` was already a dependency but there was no config, no `cypress/` | toga25-supply/cypress.config.ts, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/fixtures.ts, toga25-supply/cypress/support/mocks/useApprovalModalViewModel.ts, toga25-supply/cypress/component/SalesOrderApprovalModalsLayout.cy.tsx, toga25-supply/cypress/component/RecordApprovalModalLayout.cy.tsx, toga25-supply/cypress/component/EnterPoNumberModal.cy.tsx, toga25-supply/cypress/e2e/salesOrderApproval.cy.ts |
 | [Porting a page (or query) from toga2-supply to toga25-supply](workflows/porting-a-page-from-toga2-supply.md) | `toga25-supply` re-implements pages that already exist in `toga2-supply`. | toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/PRUDENTIAL/exportApiFields.json, toga25-supply/src/pages/SalesOrders/api/prudentialExportApi.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, toga2-supply/src/components/ui/Tables/hooks/useExportableData.tsx |

package/knowledge/2.0/apps/toga25-supply/architecture.md

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: architecture
 status: active
-updated: 2026-06-23
+updated: 2026-09-01
 owners: [apeterson]
 files:
   - toga25-supply/src/main.tsx
@@ -111,5 +111,12 @@ its primary consumer and resolves it via a symlinked `node_modules/@agilant/toga
   each other's cached data (e.g. record modal vs. approval modal — `scope="record-modal"` vs
   `scope="approval-modal"`). Including `additionalData` in the query key is mandatory for
   WHERE-filtered modal tables, or React Query serves a stale unfiltered first render.
+- **⚠ Data hooks must use `staleTime: 0` — the query cache is PERSISTED.** `App.tsx` wraps the app
+  in `PersistQueryClientProvider` with a `createSyncStoragePersister` on the `localStorage` key
+  `supply-chain-query-cache`, so cache entries survive reloads *and* sessions. The `QueryClient`
+  default is `staleTime: 0` for exactly this reason. A hook that sets its own non-zero `staleTime`
+  can serve a persisted entry from a **previous session** and never fetch — the symptom is an empty
+  list/dropdown with **nothing in the network tab**, which reads as a backend fault and is not one.
+  (`staleTime: Infinity` on the **surface-meta** hooks is a deliberate, separate exception.)
 - **Typecheck with `npx tsc --noEmit` / `npx tsc -b`** after changes; adding a required key to
   `ClientFields` surfaces every bundle missing it.

package/knowledge/2.0/apps/toga25-supply/features/transfer-orders-page.md

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-08-31
+updated: 2026-09-01
 owners: [apeterson]
 files:
   - toga25-supply/src/pages/TransferOrders/TransferOrders.tsx
@@ -19,7 +19,14 @@ files:
   - toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/view/TransferOrderRecordView.tsx
   - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/CreateTransferOrderModal.tsx
   - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/index.ts
-  - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTransferableItemRows.ts
+  - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/usePurchaseOrderItemRows.ts
+  - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTargetLocationOptions.ts
+  - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTransferSourceLocation.ts
+  - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useLocationContacts.ts
+  - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateLocationContact.ts
+  - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/AddContactModal.tsx
+  - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/TransferNotesField.tsx
+  - dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql
   - toga25-supply/src/surface/useColumnVisibilityModalConfig.ts
   - toga25-supply/src/routes.tsx
   - dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql
@@ -39,6 +46,7 @@ related:
   - ../../_underscore/features/tableview-joins.md
   - ../../api2/features/v2-rest-query-contract.md
   - ../../api2/features/tableview-field-metadata.md
+  - ../../toga-blox/features/api-client.md
   - ../../../../clients/nychh/profile.md
   - ../../../../clients/nychh/features/transfer-order-inventory-quantities.md
 ---
@@ -53,9 +61,12 @@ reserved-id seed → per-tenant TableView → per-tenant nav opt-in → surface-
 **It was fully greenfield.** An audit of production, beta, sandbox-client **and all 36 client
 databases** on 2026-08-28 found **no transfer-order TableView anywhere**. Nothing was extended.
 
-A **Create Transfer Order** modal was started the same day: the UI and its interaction rules are
-built, the data layer is **disabled behind a flag** pending three unanswered data-model questions
-(see below).
+A **Create Transfer Order** modal was started the same day and **reworked on 2026-09-01** against
+the live Claude Design export. Its data layer is wired (two of the three blocking data-model
+*questions* dissolved — availability comes from per-PO-line `_qty*`, and Locations are flat) and the
+order is scoped by a **purchase-order lock**, not by source location. 🚨 **But the picker still
+shows nothing for NYCHH**: every PO line reports availability 0 because of an upstream data gap,
+which is an open integration decision — see the blocker below.
 
 The vertical is **platform-shared with NYCHH as the first (and today only) tenant**: the Core
 surfaces and the stage theme tokens are neutral/shared, and only the TableView and the navigation
@@ -268,34 +279,85 @@ This closes the "no BUTTON_BAR surface" gap the first build left open.
   through the new `useColumnVisibilityModalConfig` hook — see
   [column-visibility](./column-visibility.md).
 
-## Create Transfer Order modal — UI built, data layer deliberately NOT faked
+## Create Transfer Order modal — the lock is on the PURCHASE ORDER, not the location
 
-`view/CreateTransferOrderModal/` (+ `hooks/useTransferableItemRows.ts`), opened from the header
-button seeded above. The interaction rules are the durable part:
+`view/CreateTransferOrderModal/`, opened from the header button seeded above. Rebuilt **2026-09-01**
+against the live Claude Design export; the three data-layer blockers below are resolved and the
+picker is live.
 
-- **Single-source lock.** The first checked row fixes the source location for the whole order.
-  Source Location is **derived and read-only — never picked**; the Location filter is pinned and
-  disabled while locked, and **restores its pre-lock value** when the lock releases.
-- **A row is an ITEM AT A LOCATION**, kept only where availability >= 1.
+> **⚠ Supersedes the earlier "single-source lock" rule.** Source Location is **no longer derived
+> from row selection**. Read the two rules below as a replacement, not an addition.
+
+- **Source Location is fixed from the moment the modal opens** — it is the single active location
+  with **`allowSending = 1`**, resolved by its own hook, and read-only. Nothing the user checks
+  changes it.
+- **The lock moved to the PURCHASE ORDER: every line on one transfer must come from the same PO.**
+  The binding is **bidirectional** — picking a PO filters the item list to that PO's lines, and
+  checking an item **locks the PO select** to that item's PO. Unlocking **restores the pre-lock
+  value**, the same restore behaviour the old location lock had.
+- **The picker columns dropped Location, Unit Value and Total** — Location is now redundant (there
+  is only one source) and the money columns are out of v1 scope.
 - **Dirty means "different from the state the form OPENED IN"**, not "different from empty" — so a
   pre-scoped open is clean, which is what makes the discard guard trustworthy.
 - **Qty error state machine:** touched on first keystroke; the error surfaces on **blur** only if
   touched; then it live-revalidates.
 - **The Review gate names the FIRST unmet condition** rather than a generic "incomplete".
 
-**Three open questions block the data layer** (the picker + fetch are written but **disabled behind
-a flag** — nothing is stubbed with fake data):
+New hooks/components: `hooks/usePurchaseOrderItemRows.ts`, `hooks/useTargetLocationOptions.ts`,
+`hooks/useTransferSourceLocation.ts`, `hooks/useLocationContacts.ts`,
+`hooks/useCreateLocationContact.ts`, `view/AddContactModal.tsx`, `view/TransferNotesField.tsx`.
+**Deleted:** `hooks/useTransferableItemRows.ts`, `hooks/usePurchaseOrderOptions.ts`.
+
+### The three original blockers
+
+1. **~~Availability per (item, location) has no API~~ — the QUESTION dissolved, but the DATA does
+   not exist.** `PurchaseOrderItems._qty*` are per-PO-line `FIELD_SQL` fields and base availability
+   bottoms out at **item receipts**, not unit dispositions — so the belief that this needed a
+   `UnitDispositions` slug (and that NYCHH's all-NULL `unitDispositionId` blocked it) was **wrong**,
+   and no new API was needed. **However NYCHH's deployed tenant override returns 0 for every line**
+   — see the blocker below.
+2. **~~The target-location picker is a TREE~~ — resolved: Locations are flat, so it is a select.**
+   No parent FK exists; the design's drill-down was dropped.
+3. **Commit flips unit dispositions to In Transit** — still open (API vs. worker ownership).
+
+### 🚨 OPEN BLOCKER — the NYCHH picker has zero selectable rows, and it is not a frontend fix
+
+The picker keeps only lines with availability >= 1. For NYCHH there are **none**, in sandbox **and**
+production.
+
+`_Model_Nychh_PurchaseOrderItem` (deployed on `_production` and `_sandbox-client`, absent on
+`_beta`/`_sandbox-dev`) sources "stock in" from inventory adjustments and `INNER JOIN`s
+`InventoryAdjustmentItems.itemFulfillmentItemId`. **That column is NULL on 100% of rows** — 292 of
+292 in sandbox, 317 of 317 in production — so `_qtyReceived`, `_qtyOnHand` and `_qtyAvailable` are
+all `0.00` for every NYCHH purchase-order line. **0 production PO lines report qty > 0.**
+
+Resolution is an **integration / data-owner decision**, not UI work: either the NetSuite integration
+backfills `InventoryAdjustmentItems.itemFulfillmentItemId`, or the override's stock-in source
+changes (base PO item receipts return real numbers today). Until then, do **not** treat an empty
+picker here as a frontend or ACL defect. Full evidence and both options:
+[NYCHH transfer-order inventory quantities](../../../../clients/nychh/features/transfer-order-inventory-quantities.md).
+
+> The `Client/2026-09-01a` role-3 `_qty*` grant is **not** the fix for this and was verified not to
+> change the response — an explicit `fields=` request bypasses `AclFieldPermissions` entirely.
+
+### ⚠ `allowReceiving` is unmaintained — do NOT filter the target dropdown on it
+
+Verified on NYCHH 2026-09-01: exactly **1 of 31** active locations sets `allowReceiving`, and it is
+**the same location** that sets `allowSending = 1` — the source warehouse. Filtering targets on
+`allowReceiving` therefore offers exactly one option: **the one place you cannot transfer to.**
 
-1. **Availability per (item, location) has no API.** `Item._qtyAvailable` is item-level with no
-   location dimension; the real source is `Units` (carries `itemId` + `locationId` + a
-   disposition). Unresolved: which `UnitDispositions` slug counts as available, and whether to
-   aggregate client-side or add a grouped table view. NYCHH has **3,226 active items**, so
-   browser-side grouping will not hold.
-2. **The design's target-location picker is a TREE** (breadcrumbs, drill-down, ancestor path), but
-   **no parent FK was found on `_Model_Client_Location`**. If Locations are flat, the dialog has to
-   become a searchable select and the design needs revisiting. Picker left disabled.
-3. **Commit flips unit dispositions to In Transit — a real inventory mutation.** Unresolved whether
-   the API owns that or a worker does.
+The dropdown lists **all active locations minus the source**. Treat `allowReceiving` as a column
+nobody populates until someone proves otherwise per tenant.
+
+Related data-shape facts found the same day:
+
+- **Contacts are sparse** — only **2 of 31** NYCHH locations have any, which is why the modal ships
+  an inline **Add Contact** path (`AddContactModal.tsx` + `useCreateLocationContact`).
+- **The populated join table is `Contacts_Locations`** (route `/contact-locations`, **Record 76**) —
+  **not** `Locations_Contacts`. Binding the reversed name finds nothing.
+- **`TransferOrders` has NO notes/description column.** The notes field's persistence is an **open
+  decision**: either `TransferOrders.description varchar(255)` (mirroring `SalesOrders`) or a
+  `TransferOrderNotes` child table (mirroring `SalesOrderNotes`). Nothing is written yet.
 
 ### Line-item fetch is off behind a FLAG, not commented out
 
@@ -357,8 +419,42 @@ visible in Core (neutral default; other tenants populate `TransferOrders.purchas
   must not be committed there. Origin/destination were picked by co-prime strides over ranked active
   `Locations` so they never collide, and the stage resolved via a ranked CTE rather than hardcoded ids.
 
+## ⚠ Two ways a hook renders an EMPTY dropdown with NOTHING in the network tab
+
+Both were hit building this modal, both look identical in the browser, and neither logs anything.
+When a select is empty **and DevTools shows no request at all**, it is one of these two — not a
+backend problem. Check them before touching the API.
+
+**1. A numeric value in `where` throws inside `buildUrl`, so React Query never fires.**
+blox's `urlEncode(input: string)` calls `input.replace()`, so a number throws
+`input.replace is not a function` **synchronously inside `queryFn`**. React Query swallows it as a
+query error — no request is ever sent. **Every `where` value must be a STRING:**
+
+```ts
+// WRONG — throws in buildUrl, no HTTP request, silent empty dropdown
+where: { "Locations.isActive": { "=": 1 } }
+
+// CORRECT
+where: { "Locations.isActive": { "=": "1" } }
+```
+
+Library-side detail: [blox API client](../../toga-blox/features/api-client.md).
+
+**2. A non-zero `staleTime` lets a cache entry from a PREVIOUS SESSION count as fresh.**
+`App.tsx` wraps the app in `PersistQueryClientProvider` with a `createSyncStoragePersister` on the
+`localStorage` key **`supply-chain-query-cache`**, so the query cache **survives reloads and
+sessions**. The `QueryClient` default is `staleTime: 0` for exactly this reason. A hook that sets
+its own `staleTime: 5 * 60 * 1000` will happily serve a **stale persisted entry from yesterday** and
+never fetch.
+
+**Rule: data hooks in this app use `staleTime: 0`.** Three of this modal's new hooks shipped with
+`5 * 60 * 1000` and had to be corrected. (`staleTime: Infinity` on the **surface-meta** hooks is a
+deliberate, separate exception — see [surface-frontend](./surface-frontend.md).)
+
 ## Gotchas
 
+- **⚠ An empty dropdown with no request in the network tab is a numeric `where` value or a
+  non-zero `staleTime`** — see the section above. Neither logs anything.
 - **A missing `AclRecordPermissions` grant on a joined record deletes a column, not a request.** The
   Status column would have silently vanished; record 351 had no grants at all.
 - **A missing `AclFieldPermissions` grant on the DEFAULT-SORT column is a 500, not a 403.** The
@@ -383,6 +479,29 @@ visible in Core (neutral default; other tenants populate `TransferOrders.purchas
   earlier migration without names, so a name-based lookup on them finds nothing.
 
 ## Change history
+- 2026-09-01 — **Rebuilt the Create Transfer Order modal against the live Claude Design export and
+  closed two of its three data-layer blockers.** The **single-source lock is superseded**: Source
+  Location is now the one active `allowSending = 1` location, read-only from open and never derived
+  from row selection; the lock moved to the **PURCHASE ORDER** (all lines must share one PO,
+  bidirectional — picking a PO filters items, checking an item locks the PO select, unlock restores
+  the pre-lock value). Picker dropped the Location / Unit Value / Total columns. Blocker 1's
+  *question* dissolved — per-PO-line availability comes from `PurchaseOrderItems._qty*`, which bottom
+  out at **item receipts, not unit dispositions**, so NYCHH's all-NULL `unitDispositionId` was never
+  relevant; blocker 2 dissolved — Locations are flat, so the tree picker became a select.
+  🚨 **But recorded a NEW open blocker: the NYCHH picker has zero selectable rows** — the deployed
+  `_Model_Nychh_PurchaseOrderItem` INNER JOINs `InventoryAdjustmentItems.itemFulfillmentItemId`,
+  which is NULL on 100% of rows (292/292 sandbox, 317/317 prod), so every PO line reports
+  availability 0. That needs an integration/data-owner decision, not UI work, and the
+  `Client/2026-09-01a` role-3 grant is **not** its fix. Recorded that
+  **`allowReceiving` is unmaintained** (1 of 31 NYCHH locations, and it is the source warehouse — so
+  filtering targets on it offers only the one place you cannot ship to), that contacts are sparse
+  (2 of 31, hence the inline Add Contact path), that the populated join is **`Contacts_Locations`**
+  (record 76), and that **`TransferOrders` has no notes column** — persistence still an open choice
+  between `description varchar(255)` and a `TransferOrderNotes` child table. Also added the
+  **two silent empty-dropdown causes**: a numeric `where` value throws inside blox's
+  `urlEncode`/`buildUrl` so no request is sent, and a non-zero `staleTime` serves a previous
+  session's entry out of the persisted `supply-chain-query-cache` — data hooks here must use
+  `staleTime: 0`. (apeterson)
 - 2026-08-31 — Recorded the **run state after sandbox-client was reset from production**: the three
   `Client_Nychh` layers and the `TransferOrderItems` timestamp columns are already present there (so
   those files insert 0 rows), the two **Core** seeds have not run, `Client/2026-08-28a` has run on

package/knowledge/clients/nychh/INDEX.md

@@ -5,5 +5,5 @@
 | [NYCHH inventory-adjustment → item-fulfillment linking (direct FK columns, REST)](features/netsuite-inventory-adjustment-fulfillment-link.md) | 1.0 | For NYCHH stock adjustments, the NetSuite **inventory adjustment** carries a link to the **Item Fulfillment** it corrects, on the multi-select body custom field | library/app/api/toga2.php, library/app/api/netsuite/rest.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_hh.php, worker/crons/toga2/netsuite/diagnose_hh_import_inventory_adjustment.php |
 | [NYCHH NetSuite → TransferOrders import (stocking-flag routing, PO bridges, origin location)](features/netsuite-transfer-order-import.md) | 1.0 | NYCHH's NetSuite **transfer orders are represented as NetSuite sales orders** (same as the GroWrk pattern), so the shared NetSuite → TOGa Supply importer (`App_ | library/app/api/toga2.php, library/app/api/netsuite/rest.php, library/app/netsuite.php, worker/crons/toga2/netsuite/sync_togasupply_hh.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/diagnose_hh_stuck_transfer_order.php, dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql, dbchanges2/Client/2026-08-28a - TransferOrderItemsTimestampColumns.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestampColumnsReposition.sql, dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql, dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.sql |
 | [NYCHH PO links are UPSTREAM — the downstream SO→PO route returns empty](features/po-number-upstream-direction.md) | 2.0 | NYCHH's sales orders are created **from the customer's purchase order**, so their SO↔PO links live in the **upstream** table `PurchaseOrders_SalesOrders` (route | _underscore/Model/Client/SalesOrder.php, _underscore/Trait/Netsuite/SalesOrder.php, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts, dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql, dbchanges2/Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql |
-| [NYCHH transfer-order 2.0 model — inventory quantities + V2 field enablement](features/transfer-order-inventory-quantities.md) | 2.0 | The 2.0 (`_underscore`) side of NYCHH transfer-order support: a **two-branch inventory quantity model** on the NYCHH `Item` override, plus the **client-override | _underscore/Model/Nychh/Item.php, _underscore/Model/Nychh/PurchaseOrderItem.php, _underscore/Model/Nychh/TransferOrder.php, _underscore/Model/Nychh/TransferOrderStage.php, _underscore/Model/Client/TransferOrder.php, _underscore/Model/Client/TransferOrderItem.php, dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql, dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql |
-| [NYC Health & Hospitals](profile.md) | 2.0 | NYC Health & Hospitals (NYCHH) is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Nychh`. | dbchanges2/Client_Nychh/2026-08-31a - PurchaseOrdersTableViewRebase.sql, dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql |
+| [NYCHH transfer-order 2.0 model — inventory quantities + V2 field enablement](features/transfer-order-inventory-quantities.md) | 2.0 | The 2.0 (`_underscore`) side of NYCHH transfer-order support: a **two-branch inventory quantity model** on the NYCHH `Item` override, plus the **client-override | _underscore/Model/Nychh/Item.php, _underscore/Model/Nychh/PurchaseOrderItem.php, _underscore/Model/Nychh/TransferOrder.php, _underscore/Model/Nychh/TransferOrderStage.php, _underscore/Model/Client/TransferOrder.php, _underscore/Model/Client/TransferOrderItem.php, dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql, dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql, _underscore/Model/Client/PurchaseOrderItem.php |
+| [NYC Health & Hospitals](profile.md) | 2.0 | NYC Health & Hospitals (NYCHH) is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Nychh`. | dbchanges2/Client_Nychh/2026-08-31a - PurchaseOrdersTableViewRebase.sql, dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql |

package/knowledge/clients/nychh/features/transfer-order-inventory-quantities.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: nychh
 type: client-feature
 status: active
-updated: 2026-08-31
+updated: 2026-09-01
 owners: [jcardinal, apeterson]
 files:
   - _underscore/Model/Nychh/Item.php
@@ -19,6 +19,8 @@ files:
   - dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql
   - dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql
   - dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql
+  - dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql
+  - _underscore/Model/Client/PurchaseOrderItem.php
 related:
   - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
   - ../../../2.0/apps/api2/features/v2-api-error-codes.md
@@ -123,6 +125,151 @@ hardening (not done): a `UNIQUE(purchaseOrderItemId, salesOrderItemId)` on the b
   `PurchaseOrderItems_TransferOrderItems`, which is currently **empty (0 rows)** in prod — so PO-level
   outbound reads 0 until the transfer-order import populates that bridge. Separate import gap, not this change.
 
+### 🚨 The override is NOT on every branch — NYCHH PO-line quantities differ per environment
+
+Verified 2026-09-01 with `git ls-tree` against each `origin/` branch of `_underscore`:
+
+| Branch | `Model/Nychh/PurchaseOrderItem.php` | Effective `_qtyReceived` for NYCHH |
+|---|---|---|
+| `_production` | **present** | inventory adjustments → **0.00 today** |
+| `_sandbox-client` | **present** | inventory adjustments → **0.00 today** |
+| `_beta` | **absent** | falls back to base → **item receipts** |
+| `_sandbox-dev` | **absent** | falls back to base → **item receipts** |
+
+Because `_underscore` is **pulled at deploy time** by branch (`.platform/hooks/prebuild/git.sh`),
+the same API request returns a **different number** depending on which tier answers it. On beta and
+sandbox-dev the base `_Model_Client_PurchaseOrderItem` runs and reports real received quantities;
+on production and sandbox-client the NYCHH override runs and reports 0.00 by design.
+
+**This is the single most misleading thing about debugging these fields.** Checking your local
+working tree tells you nothing — see the worked case below.
+
+### The BASE `_Model_Client_PurchaseOrderItem` chain (what NYCHH falls back to)
+
+Worth having written down, because it is the formula that runs wherever the override is absent, and
+because it is what a hand-run SQL check reproduces unless you deliberately pick the override. All
+are `FIELD_SQL` correlated subqueries — **none is a stored column**
+(`_underscore/Model/Client/PurchaseOrderItem.php`, ~L41–158):
+
+| Field | Base definition |
+|---|---|
+| `_qtyReceived` | `SUM(ItemReceiptItems.quantity)` where `purchaseOrderItemId = PurchaseOrderItems.id` |
+| `_qtyFulfilled` | `SUM(ItemFulfillmentItems.quantity)` through `PurchaseOrderItems_TransferOrderItems → ItemFulfillments → ItemFulfillmentStages → ItemFulfillmentStatuses`, restricted to status slug **`SHIPPED`** (i.e. shipped on a linked **transfer** order) |
+| `_qtyOnHand` | `_qtyReceived − _qtyFulfilled` |
+| `_qtyCommitted` | `SUM(SalesOrderItems.qtyCommitted) − SUM(shipped ItemFulfillmentItems.quantity)`, both reached via `PurchaseOrders_SalesOrders` and matched on `VendorItems.id = PurchaseOrderItems.vendorItemId` — **matched by VENDOR ITEM, not by PO line** |
+| `_qtyAvailable` | `_qtyOnHand − _qtyCommitted` |
+
+**Two things follow that were previously believed otherwise:**
+
+- **Base availability bottoms out at ITEM RECEIPTS, not unit dispositions.** This dissolves the
+  earlier blocker that "availability needs `Units` + a `UnitDispositions` slug" — NYCHH units all
+  carry `NULL unitDispositionId`, which turned out to be irrelevant to these fields. It is what
+  unblocked the Create Transfer Order item picker (see
+  [Transfer Orders page](../../../2.0/apps/toga25-supply/features/transfer-orders-page.md)).
+- **`_qtyCommitted` matches by vendor item, not by PO line**, so at base it can attribute
+  commitment from a *different* PO line carrying the same `vendorItemId`. The NYCHH override
+  replaces it with a PO-line-scoped Transfer-Order commitment precisely to avoid this.
+
+### ⚠ Worked case — "the API returns 0 but the SQL returns 40" (diagnosed 2026-09-01)
+
+`GET /v2/purchase-order-items` returned `_qtyReceived/_qtyOnHand/_qtyFulfilled/_qtyAvailable: 0`
+for every line on sandbox-client, while the *same*-looking subquery run by hand on the *same* host
+returned **40.00**.
+
+**Cause: the two were never the same SQL.** Both formulas run against the reference row
+(sandbox `Client_Nychh`, `PurchaseOrderItems.id = 196`, uuid
+`01110c53-ba73-e60a-d94c-0ccf77327c0e`, PO 80622 line 1):
+
+| Expression | `_qtyReceived` |
+|---|---|
+| base `_Model_Client_PurchaseOrderItem::_qtyReceived` (item receipts) | **40.00** |
+| `_Model_Nychh_PurchaseOrderItem::_qtyReceived` (inventory adjustments) | **0.00** |
+
+The hand-run check used the base formula; the API ran the NYCHH override. **The API was reporting
+correctly** — but see the blocker below, because "correct" here means "0 for every line".
+
+**Why the override was wrongly eliminated:** `_underscore/Model/Nychh/` was listed in the **local
+working tree**, which sits on branch `features-talos-transferorders` and does not carry the file.
+Branch drift *was* also checked — but only on `Model/Client/PurchaseOrderItem.php`, which is
+byte-identical across all four branches. **That passing sibling check is what made the wrong
+conclusion feel safe.** The drift was one directory over.
+
+**The generalisable rules:**
+
+1. **Check a tenant model override on the DEPLOYED branch, never on the local working tree.**
+   ```
+   git cat-file -e origin/<branch>:Model/<Slug>/<Model>.php && echo present || echo absent
+   ```
+   A feature branch is not evidence about production.
+2. **A base file being byte-identical across branches rules out drift in THAT FILE ONLY.** It says
+   nothing about `Model/<Tenant>/`. Re-run the check there before writing the elimination down —
+   a clean sibling result is the trap, not the reassurance.
+3. **A calculated field disagreeing with hand-run SQL means two different expressions are running.**
+   Identify the emitting class first; ACL, `calcDepth`, wrong DB and deploy lag are all downstream
+   of that and were each eliminated here at real cost.
+
+Also eliminated and worth not repeating: ACL (bypassed entirely on the explicit-`fields=` path —
+see [v2-rest-query-contract](../../../2.0/apps/api2/features/v2-rest-query-contract.md)),
+`calcDepth` (echoed 3; the gate at `V2.php:7231` is `depth <= calcDepth`), wrong database
+(`Core.DatabaseHosts` maps "Sandbox Client" for `Client_Nychh` to
+`client.sandbox.database.togahub.com`, matching the API the frontend targets), deploy lag (the base
+`_qtyReceived` formula is unchanged across the 2026-08-19 rewrite), wrong table
+(`_Model_Client_ItemReceiptItem::TABLE = 'ItemReceiptItems'`), and missing data (sandbox has 823 PO
+lines, 207 `ItemReceiptItems`, 122 lines with available >= 1).
+
+### 🚨 OPEN BLOCKER — the override reads 0 for 100% of NYCHH PO lines, in sandbox AND production
+
+The override's chain `INNER JOIN`s
+`InventoryAdjustmentItems ON itemFulfillmentItemId = ItemFulfillmentItems.id`. **That column is
+NULL on every row in both environments** (verified 2026-09-01):
+
+| Environment | `InventoryAdjustmentItems` rows | rows with `itemFulfillmentItemId` set |
+|---|---|---|
+| sandbox `Client_Nychh` | 292 | **0** |
+| production `Client_Nychh` | 317 | **0** |
+
+Production PO lines the override would report with qty > 0: **0, out of all lines.**
+
+An INNER JOIN makes an unlinked adjustment contribute nothing, so `_qtyReceived` — and therefore
+`_qtyOnHand` and `_qtyAvailable` — is **0.00 for every NYCHH purchase-order line today.**
+
+This is precisely the "Old-data caveat" the override file states in its own header comment (NetSuite
+began linking inventory adjustments to fulfillments less than a year ago; unlinked adjustments carry
+a NULL `itemFulfillmentItemId` and are excluded until the integration backfills them). **It is not a
+corner case — it is currently 100% of the data.**
+
+**Consequence: the Create Transfer Order item picker cannot show a single selectable line for
+NYCHH.** The picker keeps only rows with availability >= 1, and there are none. This is
+**unresolved and needs a decision from the integration / data owner** — it is *not* a frontend fix.
+Two options:
+
+- **(a)** the NetSuite integration backfills `InventoryAdjustmentItems.itemFulfillmentItemId`, or
+- **(b)** the override's definition of "stock in" is changed (e.g. back to PO item receipts, which
+  return real numbers today — 40.00 on the reference row).
+
+Until one of those lands, treat any NYCHH transfer-order availability figure as **structurally 0**,
+not as a bug to debug. Tracking the adjustment↔fulfillment link:
+[NYCHH inventory-adjustment → item-fulfillment linking](./netsuite-inventory-adjustment-fulfillment-link.md).
+
+### The role-3 grant migration is NOT the fix for the empty picker
+
+`dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql` grants **role 3 (API)**
+READ (`isWritable = 0`) on all eight `_qty*` `RecordFields` (**1500–1504, 1524–1526**), guarded by
+`NOT EXISTS` on the `(recordFieldId, roleId)` unique key.
+
+**It was written against a wrong theory and was verified NOT to change the response** — an explicit
+`fields=_qtyX` request never consults `AclFieldPermissions` at all. Nothing about the empty picker
+is a permission problem; the cause is the data gap in the section above.
+
+**Keep it anyway.** It closes a real and *separate* gap on the `getFullModelData()` (no-explicit-
+`fields=`) path, where these fields genuinely are ACL-gated, and 31 of 36 prod tenants have the same
+hole. It was **applied on sandbox `Client_Nychh`** and is **cleanly reversible** via its eight
+hardcoded uuid literals (`DELETE … WHERE uuid IN (…)`) — which is why it uses literals rather than
+generated uuids; see
+[re-runnable additive migrations](../../../2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md).
+Fleet survey and the "grant explicitly, don't mirror a sibling" rule it produced:
+[ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md).
+
 ### Index coverage / schema
 
 No `dbchanges2` file — pure calculated `FIELD_SQL` in PHP. All correlation columns
@@ -226,8 +373,42 @@ pattern (default a NOT NULL non-writable column in the model, never send it) is
 - **A 0.00 quantity for NYCHH is expected today, not a bug.** Stock-in reads inventory-adjustment links
   that are not backfilled yet, and PO-level outbound reads a still-empty
   `PurchaseOrderItems_TransferOrderItems` bridge (see above).
+- 🚨 **Every NYCHH PO line reads `_qtyReceived`/`_qtyOnHand`/`_qtyAvailable` = 0.00 right now**, in
+  sandbox **and** production, because `InventoryAdjustmentItems.itemFulfillmentItemId` is NULL on
+  100% of rows and the override INNER JOINs on it. Blocks the Create Transfer Order picker; needs an
+  integration/data decision, not code. See the OPEN BLOCKER section.
+- **⚠ `_Model_Nychh_PurchaseOrderItem` is on `_production`/`_sandbox-client` but NOT on
+  `_beta`/`_sandbox-dev`** — so NYCHH PO-line quantities are genuinely different numbers per tier.
+  Establish the deployed `_underscore` branch before comparing environments or trusting a repro.
+- **Never eliminate a tenant model override by `ls`-ing your working tree.** Use
+  `git cat-file -e origin/<deployed-branch>:Model/<Slug>/<Model>.php`. This exact mistake cost a
+  session — and a *passing* drift check on the base `Model/Client/` file is what made it feel safe.
 
 ## Change history
+- 2026-09-01 — **Diagnosed the "API returns 0, hand-run SQL returns 40" report, and it turned into a
+  data blocker rather than a bug.** The API ran `_Model_Nychh_PurchaseOrderItem`'s
+  inventory-adjustment `_qtyReceived` while the hand-run check used the **base** item-receipt
+  formula — on the reference row (`PurchaseOrderItems.id 196`, PO 80622 line 1) the base returns
+  **40.00** and the override **0.00**. 🚨 **The override returns 0 for 100% of NYCHH PO lines in
+  both sandbox and production**: it INNER JOINs
+  `InventoryAdjustmentItems.itemFulfillmentItemId`, which is NULL on **all** rows (292 sandbox /
+  317 prod, 0 linked; 0 prod PO lines report qty > 0). The file's own "old-data caveat" is
+  currently the entire dataset, so the **Create Transfer Order item picker cannot show any
+  selectable NYCHH line** — recorded as an **open blocker needing an integration/data-owner
+  decision** (backfill the FK, or change the override's stock-in source), explicitly not a frontend
+  fix. Also found `Model/Nychh/PurchaseOrderItem.php` present on **`_production` + `_sandbox-client`**
+  and **absent from `_beta` + `_sandbox-dev`** (verified with `git cat-file -e`), so PO-line
+  quantities differ per tier; the override had been wrongly eliminated by listing the **local**
+  working tree on a feature branch that lacks it, while the drift check covered only
+  `Model/Client/PurchaseOrderItem.php` — the passing sibling check is what made the wrong conclusion
+  feel safe. Documented the **base `_qty*` chain** (received = `ItemReceiptItems`; fulfilled =
+  SHIPPED transfer-order fulfillments; committed matched **by vendor item, not PO line**), which
+  establishes that base availability bottoms out at **item receipts, not unit dispositions** —
+  dissolving the belief that NULL `unitDispositionId` was the blocker. Corrected the framing of
+  `Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql`: it is **not** the fix for the
+  empty picker and was verified not to change the response (explicit `fields=` bypasses ACL); it
+  remains a real separate gap on the `getFullModelData()` path, was applied on sandbox
+  `Client_Nychh`, and is cleanly reversible via its eight hardcoded uuid literals. (apeterson)
 
 - 2026-08-31 — **Stock-in flipped from PO item receipts → inventory adjustments** (per the 2026-08-27
   TOGa Supply meeting: NetSuite has no stocking concept, stock is added only by an inventory adjustment

package/knowledge/clients/nychh/profile.md

@@ -26,6 +26,7 @@ files:
   - dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql
   - dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql
   - dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql
+  - dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql
 related:
   - ../../2.0/apps/_underscore/features/tracking-number-bridges.md
   - ../../2.0/apps/_underscore/features/tableview-joins.md
@@ -99,8 +100,9 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   `Client_Nychh/`**, because the client files reference Core record ids and the NYCHH TableView/ACL
   need the columns the fan-out files add. Run state per environment must be **verified against that
   environment**, never assumed from the repo. **beta is blocked** because it lacks the
-  `TransferOrderStages` table. A **Create Transfer Order** modal is started (UI built, data
-  layer flagged off pending three open data-model questions). See
+  `TransferOrderStages` table. The **Create Transfer Order** modal was reworked 2026-09-01 and its
+  data layer is wired, but 🚨 **the item picker shows zero selectable lines for NYCHH** — see the
+  availability blocker below. See
   [Transfer Orders page](../../2.0/apps/toga25-supply/features/transfer-orders-page.md).
 - 🚨 **The transfer-order ACL + schema on prod/sandbox are UNTRACKED (2026-08-28).** Record and field
   ACL for records 312/313, their logic-group/expression chain, and the
@@ -114,6 +116,32 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   fulfilled/backordered model on `_Model_Nychh_Item`, plus the client-override models + ACL rows that
   let a NetSuite TransferOrder POST succeed. See
   [NYCHH transfer-order inventory & quantities](./features/transfer-order-inventory-quantities.md).
+- 🚨 **OPEN BLOCKER — every NYCHH PO line reports availability 0, in sandbox AND production
+  (verified 2026-09-01).** The deployed `_Model_Nychh_PurchaseOrderItem` sources stock-in from
+  inventory adjustments and `INNER JOIN`s `InventoryAdjustmentItems.itemFulfillmentItemId`, which is
+  **NULL on 100% of rows** (292/292 sandbox, 317/317 prod). So `_qtyReceived` / `_qtyOnHand` /
+  `_qtyAvailable` are all `0.00` for every purchase-order line, and the **Create Transfer Order item
+  picker has nothing to show**. Needs an **integration / data-owner decision** — backfill the FK, or
+  change the override's stock-in source (base PO item receipts return real numbers today). Not a
+  frontend or ACL defect, and **not** fixed by `Client/2026-09-01a`. See
+  [NYCHH transfer-order inventory & quantities](./features/transfer-order-inventory-quantities.md).
+- 🚨 **`_Model_Nychh_PurchaseOrderItem` is NOT on every `_underscore` branch (verified 2026-09-01).**
+  `Model/Nychh/PurchaseOrderItem.php` exists on **`_production`** and **`_sandbox-client`** but is
+  **absent from `_beta`** and **`_sandbox-dev`**. Because `_underscore` is pulled at deploy by
+  branch, NYCHH PO-line `_qty*` values are **different numbers per tier**: prod/sandbox-client run
+  the inventory-adjustment formula (0.00 until the NetSuite link is backfilled), beta/sandbox-dev
+  fall back to the base item-receipt formula and report real quantities. **Never eliminate a tenant
+  override by `ls`-ing your working tree** — use
+  `git ls-tree -r --name-only origin/<branch>`. That mistake cost a full session chasing a
+  non-existent "API returns 0" bug. See
+  [NYCHH transfer-order inventory & quantities](./features/transfer-order-inventory-quantities.md).
+- **Create Transfer Order modal is scoped by PURCHASE ORDER, not by location (2026-09-01).** Source
+  Location is the one active `allowSending = 1` location, read-only from open; all lines on a
+  transfer must share one PO. `Locations.allowReceiving` is **unmaintained** for this tenant (1 of 31
+  active locations, and it is the source warehouse), so the target dropdown lists all active
+  locations minus the source. Contacts are sparse (2 of 31) and the populated join is
+  **`Contacts_Locations`** (record 76), not `Locations_Contacts`. See
+  [Transfer Orders page](../../2.0/apps/toga25-supply/features/transfer-orders-page.md).
 - **Inventory-adjustment → item-fulfillment linking** — imports NetSuite `custbody_stock_adjustment`
   (adjustment→fulfillment) into two all-client bridges for adjustment→fulfillment→SO→PO traceability;
   gated NYCHH-only, best-effort, with on-demand fulfillment import. Go-live toggle

package/knowledge/sessions/2026-09-01-transfer-orders-qty-blocker-apeterson.md

@@ -0,0 +1,109 @@
+---
+type: session
+slug: transfer-orders-qty-blocker
+title: NYCHH Transfer Orders item picker empty — root-caused to the Nychh _qtyReceived override
+author: apeterson
+repos: [toga25-supply, dbchanges2, api2, _underscore]
+framework: "2.0"
+client: nychh
+status: active
+created: 2026-09-01
+updated: 2026-09-01
+---
+
+# Session: transfer-orders-qty-blocker
+**Date:** 2026-09-01
+**Project/Repo:** toga25-supply (2.0), with dbchanges2; api2 + _underscore read-only
+**Task:** Finish the NYCHH Create Transfer Order modal (contact picker, notes, PO select, item picker) and find out why the item picker renders empty even though `/purchase-order-items` returns 823 rows.
+
+---
+
+## What WORKED
+
+- **ROOT CAUSE FOUND.** `_Model_Nychh_PurchaseOrderItem` overrides `_qtyReceived` to source stock-in from **inventory adjustments** instead of item receipts. Verified both formulas against the same row (sandbox `Client_Nychh`, `PurchaseOrderItems.id = 196`, uuid `01110c53-ba73-e60a-d94c-0ccf77327c0e`, PO 80622 line 1):
+  - base `_Model_Client_PurchaseOrderItem::_qtyReceived` → **40.00**
+  - `_Model_Nychh_PurchaseOrderItem::_qtyReceived` → **0.00**
+- **Why the override yields 0** — its chain does `INNER JOIN InventoryAdjustmentItems ON itemFulfillmentItemId = ItemFulfillmentItems.id`, and that column is NULL on every row:
+  - sandbox `Client_Nychh`: 292 `InventoryAdjustmentItems`, **0** with `itemFulfillmentItemId` set
+  - production `Client_Nychh`: 317 `InventoryAdjustmentItems`, **0** with `itemFulfillmentItemId` set
+  - production PO lines the override reports with qty > 0: **0**
+  This is the override file's own documented "old-data caveat" (NetSuite only began linking adjustments to fulfillments within the last year) — currently it is 100% of the data, not a corner case.
+- **Correct way to detect a tenant model override** — `git cat-file -e origin/<branch>:Model/<Slug>/<Model>.php`. Confirmed PRESENT on `origin/_sandbox-client` and `origin/_production`, absent on `origin/_beta` and `origin/_sandbox-dev`.
+- **Documented the full `_qty*` formula chain** from `_underscore/Model/Client/PurchaseOrderItem.php` (lines 41–158): `_qtyReceived` = SUM(ItemReceiptItems.quantity); `_qtyFulfilled` = shipped ItemFulfillmentItems via `PurchaseOrderItems_TransferOrderItems`; `_qtyOnHand` = received − fulfilled; `_qtyCommitted` = SO qtyCommitted − shipped, matched by **vendor item** not PO line; `_qtyAvailable` = onHand − committed.
+- **Fixed: numeric `where` values silently cancel the request.** blox `urlEncode(input: string)` calls `input.replace()`, so a numeric `1` throws inside `buildUrl` → `queryFn`. React Query swallows it and **no HTTP request is sent** — an empty dropdown with nothing in the network tab. Corrected to `{ "Locations.isActive": { "=": "1" } }` in `useTargetLocationOptions.ts` and `useTransferSourceLocation.ts`; the target-location and PO dropdowns then issued requests.
+- **Fixed: non-zero `staleTime` suppresses fetches across sessions.** `App.tsx` uses `PersistQueryClientProvider` + `createSyncStoragePersister` on localStorage key `supply-chain-query-cache`, and the QueryClient default is `staleTime: 0`. Three new hooks had `staleTime: 5*60*1000`, letting a persisted entry from an earlier session count as fresh. All set to 0.
+- **Ran `Core/2026-09-01a - TransferOrderCreatePoColumnAndFilter.sql` successfully on sandbox** — message 288, SurfaceElements 214 (PO column) + 215 (poFilter), absolute `CASE` sortOrder assignment, `isVisible = 0` on 209/211/213. Confirmed by the resulting sortOrder rows.
+- **Wrote and ran `Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql`** on sandbox `Client_Nychh` — 8 role-3 grants landed, verified. (It is NOT the fix; see below.)
+- **Fleet ACL survey (production, 36 client DBs)** — 31 grant all eight `_qty*` to role 1 and none to role 3; 4 (Compass, Imhouston, Mcgrawhill, Tdsynnex) have none at all; only Prudential (roles 1+3) and Northwell (role 3) are correct.
+- **Verified `Core.Records`/`Core.RecordFields` ids are identical between production Core and sandbox Core** for record 18 — this is what makes literal id references safe in `Client/` migrations.
+- **Knowledge captured and pushed** — commit `261d8e7` on `_main`, 9 docs, validate OK (32 repos).
+
+## What did NOT work — DO NOT RETRY THESE
+
+- **Granting `AclFieldPermissions` to role 3 does NOT fix the empty picker.** The 8 grants landed and the response was byte-for-byte unchanged — still `_qtyAvailable: 0`. Reason: `V2.php:3338` classifies a field as calculated when `$modelFieldConfig[$f]['type'] == _Model::FIELD_SQL`, and that branch runs **before** the ACL branch at `:3353` and checks no permissions. An explicit `fields=_qtyAvailable` therefore bypasses `AclFieldPermissions` entirely. The ACL gate for calc fields is at `V2.php:7216`, which is the *no-explicit-fields* (`getFullModelData`) path only.
+- **Checking `Core.AclFieldPermissions` for record 18 is meaningless.** `Core.Records.id = 18` has `aclDatabase = CLIENT`, so grants are read from `Client_<Tenant>.AclFieldPermissions`. I checked Core, got a confident answer, and it sent the investigation down a wrong path for a long stretch.
+- **Eliminating the tenant model override by listing the local working tree.** `ls Model/Nychh/` showed 21 files and no `PurchaseOrderItem.php` — because the local checkout is on branch `features-talos-transferorders`, which does not carry it. The file **is** on the deployed branches. This single wrong elimination is why the root cause took so long.
+- **Trusting the sibling drift check.** `git diff origin/_sandbox-client -- Model/Client/PurchaseOrderItem.php` was empty and all four branches are byte-identical — a true result that made the override elimination feel safe. The drift was one directory over, in `Model/Nychh/`.
+- **Mirroring a sibling field's roles in an ACL grant migration.** Drafted it (matching house precedent `Client/2026-07-22c`) and rejected it before shipping: Compass grants `quantity` to **role 4 (Public)**, so the mirror would have handed Public read on eight derived inventory quantities, and Imhouston has no `quantity` grant so the mirror would have silently inserted nothing there.
+- **Reading `Core.RecordFields` from a `Client/` migration.** First draft did this (copying `Client/2026-07-22c`); the `dbchanges2-cluster-isolation.js` PreToolUse hook blocked it, correctly. Verified on production that the client cluster (reader **and** writer endpoints) hosts only `Client_*` databases — no `Core`. `2026-07-22c` is a shipped violation, not a pattern to copy.
+- **Inferring a table's column list from a sibling migration's VALUES row.** Produced `Unknown column 'slug' in 'field list'`. `Core.Messages` columns are `(id, uuid, dtCreated, messageKey, name, defaultValue)`.
+- **`ON DUPLICATE KEY UPDATE id = id` on literal-id rows** — self-caught before running; violates the rule that a stolen team-assigned id must fail loudly. Replaced with `NOT EXISTS` guards on the natural key.
+- **Relative `sortOrder + 1` shift guarded by a subquery on the table being updated** — MySQL error 1093 risk. Replaced with an idempotent absolute `CASE` assignment that needs no guard.
+- **Flipping `[debug] show_queries` in `Config/sandbox-client.ini`** — was queued as the next diagnostic and is now unnecessary. There is nothing left to find in the query.
+- **`ERROR 1054 Unknown column 'f.sql'` on `Core.RecordFields`** — the table has no `sql` column; calculated-field SQL lives in the `_underscore` model as `FIELD_SQL` static methods.
+- **`SELECT ... slug FROM Roles`** — the client `Roles` table has no `slug` column (id, name only).
+
+## Not tried yet (candidates for next session)
+
+- **Decide the stock-in source for NYCHH.** Either (a) get the NetSuite integration to backfill `InventoryAdjustmentItems.itemFulfillmentItemId`, or (b) change `_Model_Nychh_PurchaseOrderItem::_qtyReceived`. This is the actual blocker and is an integration/data-owner call (Jason owns the availability-decrement behavior).
+- **Ask why the NYCHH override exists at all** — if item receipts are the truth for availability, the override may simply be wrong for this use case rather than needing a backfill.
+- **Notes persistence** — `TransferOrders` has no notes/description column. Options: `TransferOrders.description varchar(255)` mirroring `SalesOrders`, or a `TransferOrderNotes` child table mirroring `SalesOrderNotes`.
+- **Build the review step** — currently a placeholder ("Review step — not built yet"); the Create button is disabled.
+- **Strip the diagnostics** — `_qtyReceived`/`_qtyFulfilled` were added to `PO_ITEM_FIELDS` purely to diagnose, and `sampleBreakdown` threads through to the empty-state message. Remove both once the blocker is resolved.
+- **Decide whether `Client/2026-09-01a` should fan out to all tenants** or stay NYCHH-only. It is currently applied to sandbox `Client_Nychh` only.
+- **`allowReceiving` data hygiene** — decide whether the flag should be maintained so the target dropdown can filter on it.
+- **Flag `Client_Compass_20260831_120000`** — a dated backup database on the production client cluster that any `Client/` fan-out would hit.
+- Parked, do not resume unasked: Line Items + Units columns, Target Contact column on the list table, the status 5→3 vocabulary relabel, Target Location path rendering, the location pin icon.
+
+## Current file state
+
+| File | Status | Notes |
+|------|--------|-------|
+| `toga25-supply/.../CreateTransferOrderModal/CreateTransferOrderModal.tsx` | Modified, uncommitted | Bidirectional PO binding (`lockedPo`/`preLockPoRef`/`wasLockedRef`), search input first then PO select, `FILTER_ROLES` splits controls from columns, empty-state cascade names the real cause |
+| `toga25-supply/.../hooks/usePurchaseOrderItemRows.ts` | Created, uncommitted | Fetches all PO lines, derives PO options; still carries the `_qtyReceived`/`_qtyFulfilled` + `sampleBreakdown` diagnostics |
+| `toga25-supply/.../hooks/useTargetLocationOptions.ts` | Created, uncommitted | All active locations minus source; `where` values are strings; `staleTime: 0` |
+| `toga25-supply/.../hooks/useTransferSourceLocation.ts` | Created, uncommitted | Resolves the single `allowSending` location; exports `formatLocationAddress`; returns `hasAmbiguousSource` |
+| `toga25-supply/.../hooks/useLocationContacts.ts` | Created, uncommitted | Route `/contact-locations` (Record 76); `DEFAULT_CONTACT_TYPE = "SHIPPING"` |
+| `toga25-supply/.../hooks/useCreateLocationContact.ts` | Created, uncommitted | POST `/contacts` then POST `/contact-locations` |
+| `toga25-supply/.../view/AddContactModal.tsx` | Created, uncommitted | Two required names, capture-phase Escape, own scrim |
+| `toga25-supply/.../view/TransferNotesField.tsx` | Created, uncommitted | `useAutoGrow`, `FieldClear`, Escape blurs |
+| `toga25-supply/.../view/TransferItemPickerTable.tsx` | Modified, uncommitted | Type renamed `PurchaseOrderItemRow`; caller-owned `emptyMessage` |
+| `toga25-supply/.../hooks/useTransferableItemRows.ts` | Deleted, uncommitted | Superseded |
+| `toga25-supply/.../hooks/usePurchaseOrderOptions.ts` | Deleted, uncommitted | Superseded — options now derived from item rows |
+| `dbchanges2/Core/2026-09-01a - TransferOrderCreatePoColumnAndFilter.sql` | Created, uncommitted | **RUN on sandbox, succeeded** |
+| `dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql` | Created, uncommitted | **RUN on sandbox `Client_Nychh`, succeeded** — but is NOT the fix; reversible via its 8 uuid literals |
+| `toga-tech/knowledge/**` (9 docs) | Committed + pushed | Commit `261d8e7` on `_main` |
+
+`npx tsc --noEmit` from the toga25-supply root: exit 0, clean. Nothing committed or pushed in any project repo.
+
+## Decisions made
+
+- **Grant role 3 explicitly rather than mirroring a sibling field's roles.** Rationale: mirroring `quantity` would have granted Compass's role 4 (Public) eight derived inventory quantities and would have inserted nothing on Imhouston. Rejected: the house precedent `Client/2026-07-22c`, which mirrors.
+- **Use hardcoded v4 uuid literals, not `UUID()`, in fan-out ACL grant migrations.** Rationale: rollback becomes exact — `DELETE ... WHERE uuid IN (<literals>)` removes only the rows that file created and cannot touch Prudential's/Northwell's pre-existing role-3 grants. A rollback keyed on `(recordFieldId, roleId)` would have deleted theirs. uuid is unique per table per database, so one literal reused across tenants is valid. Rejected: the house habit of `UUID()` "so each client's rows are distinct" — it buys nothing here and costs the clean undo.
+- **Reference `Core.RecordFields` ids as literals in `Client/` migrations.** Rationale: Core is on a separate cluster in production, so a `Core.*` lookup resolves only in non-prod; `Records`/`RecordFields` ids are team-assigned and verified identical across environments. Rejected: the cross-database lookup used by `2026-07-22c`.
+- **Target Location lists all active locations minus the source, NOT filtered on `allowReceiving`.** Rationale: exactly 1 of NYCHH's 31 active locations has `allowReceiving = 1`, and it is the same location that has `allowSending = 1` — filtering would offer only the place you cannot transfer to. The flag is unmaintained for this tenant.
+- **Source Location is resolved by flag (`allowSending = 1`), read-only from modal open** — not derived from row selection and not hardcoded. Rationale: another tenant, or a NYCHH rename, then needs no code change. The old selection-derived source lock was replaced by the PO lock.
+- **The PO lock replaces the location lock** — all lines on one transfer must come from the same purchase order, per the live Claude Design export.
+
+## Blockers
+
+- **HARD BLOCKER — no NYCHH PO line reports available stock, in sandbox or production.** `_Model_Nychh_PurchaseOrderItem::_qtyReceived` INNER JOINs `InventoryAdjustmentItems.itemFulfillmentItemId`, which is NULL on all 292 sandbox rows and all 317 production rows. Production PO lines with qty > 0: 0. The Create Transfer Order item picker cannot show a selectable line until either the NetSuite integration backfills that FK or the override's stock-in source changes. **This is an integration/data-owner decision, not a frontend fix.**
+- **Demo trap:** the override is absent from `_beta` and `_sandbox-dev`, so those tiers fall back to the base item-receipt formula and **will show a working picker with real quantities**. A beta demo will look healthy while production is structurally empty. Do not read beta as evidence the feature works.
+- Notes field has nowhere to persist (`TransferOrders` has no notes/description column).
+
+## Exact next step
+
+> Take the blocker to Jason and the NetSuite integration owner with these two numbers: production `Client_Nychh` has 317 `InventoryAdjustmentItems` and **0** with `itemFulfillmentItemId` set, so `_Model_Nychh_PurchaseOrderItem::_qtyReceived` returns 0.00 for every PO line. Ask which of the two fixes they want — backfill `InventoryAdjustmentItems.itemFulfillmentItemId`, or change the override's stock-in source (base `_Model_Client_PurchaseOrderItem::_qtyReceived` uses `ItemReceiptItems` and returns 40.00 for `PurchaseOrderItems.id = 196`). No further frontend work on the item picker until that is answered.
+
+---
+_Saved by /session-save on 2026-09-01_

package/package.json

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