toga-ai 1.0.790 → 1.0.792

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

@@ -6,13 +6,14 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-01
+updated: 2026-09-10
 owners: [snaredla, jcardinal, bala]
 files:
   - _underscore/Model.php
   - _underscore/Model/Client/PurchaseOrder.php
   - _underscore/Model/Client/SalesOrder.php
   - _underscore/Model/Client/ServiceRequest.php
+  - _underscore/Model/Client/Location.php
   - _underscore/Model/Elite/SalesOrder.php
   - _underscore/Model/Compass/SalesOrder.php
   - _underscore/Model/Compass/Canada/SalesOrder.php
@@ -30,6 +31,8 @@ related:
   - ./model-magic-field-access.md
   - ./model-save-parent-cascade-stored-field-deadlock.md
   - ./sales-order-purchase-order-bridge-direction.md
+  - ../../../../clients/nychh/features/location-shipping-addresses.md
+  - ../../toga25-supply/features/transfer-orders-page.md
 ---
 
 ## Summary
@@ -95,6 +98,45 @@ Verified 2026-08-26 on `_Model_Quad_Item::_unitPrice`, which returns a `GROUP_CO
 `'CODE amount'` pairs across a Quad item's currencies (see
 [Quad multi-currency item pricing](../../../../clients/quad/features/multi-currency-item-pricing.md)).
 
+## ⚠ A calculated field must return the HUMAN value, not the FK id (`_addressState`, 2026-09-10)
+
+`_Model_Client_Location` exposes the location's address as calculated fields
+(`_addressLine1/_addressLine2/_addressCity/_addressState/_addressZip`). `_addressState` selected
+**`Addresses.stateId`**, so every consumer rendered the internal id: `Bronx, 33 10451-5504` instead
+of `Bronx, NY 10451-5504`. A calculated field is a **display** field — resolve the lookup inside the
+subquery rather than handing the caller an id it cannot translate.
+
+The fix joins `States` inside the existing subquery (`Model/Client/Location.php`, ~L66):
+
+```php
+LEFT JOIN States ON States.id = Addresses.stateId
+... SELECT States.code ...
+```
+
+**`LEFT JOIN`, not `INNER`** — `Addresses.stateId` is nullable, and an inner join would drop the
+whole address line for a state-less address. This matches the existing pattern in
+`_underscore/Model/Rate/SalesOrder.php`.
+
+### The blast-radius checklist for changing a shared `_Model_Client_*` calculated field
+
+This is a **shared core model**: one edit ships to every tenant at once, and a calculated field has
+no compile-time consumers, so the only way to know who breaks is to look. What was checked before
+this one-line change, and the shape to reuse:
+
+1. **Does every client schema support the new join?** All **36** `Client_*` prod schemas have both a
+   `States` and a `Locations` table, so no tenant errors on the join.
+2. **Who reads the field, and do they DISPLAY it or DECIDE on it?** Only two frontends request
+   `_addressState` and both only print it (`toga25-supply` TransferOrders hooks, and
+   `toga2-supply/src/pages/Inventory/api/InventoryApi.tsx` ~L560).
+3. **Does any metadata treat it as an id?** `Core.RecordFields` id **73** is `_addressState`, with
+   **0** rows in `SurfaceElements` and `DefaultRecordFieldSettings` and one ACL read row — nothing
+   configures it as an id-based filter, so nothing depended on getting a number.
+4. **Run the new subquery against production before committing.** The edited expression returned
+   `NY` for all 24 NYCHH locations; `php -l` alone proves nothing about a SQL string.
+
+> **Status 2026-09-10: written, `php -l` clean, UNCOMMITTED on `_production` and NOT deployed.**
+> Production still renders the state id until it ships.
+
 ## Exposing a calculated field to the API - a client `CustomRecordFields` row is enough
 
 **Declaring the field on the model does not make it requestable.** A client whose DB has no
@@ -211,6 +253,15 @@ characters — that is the standard of evidence for touching a field that runs o
   [save-cascade stored-field deadlocks](./model-save-parent-cascade-stored-field-deadlock.md).
 
 ## Change history
+- 2026-09-10 — **Fixed `_Model_Client_Location::_addressState()` to return the state CODE, not
+  `Addresses.stateId`** (addresses rendered as `Bronx, 33 10451-5504`). Added
+  `LEFT JOIN States ON States.id = Addresses.stateId` inside the subquery and selected `States.code`
+  — LEFT because `stateId` is nullable, matching `_underscore/Model/Rate/SalesOrder.php`. Recorded
+  the **blast-radius checklist** used before touching a shared calculated field: all 36 prod
+  `Client_*` schemas have `States` + `Locations`; only two frontends read the field and both only
+  display it; `Core.RecordFields` 73 has no `SurfaceElements`/`DefaultRecordFieldSettings` rows, so
+  no filter relied on the numeric value; and the new subquery was run against prod (returned `NY`
+  for all 24 NYCHH locations). **Uncommitted / not deployed** as of this date. (bala)
 - 2026-09-01 — Added `_shipTo` to the base `_Model_Client_PurchaseOrder` (`public $_shipTo =
   self::FIELD_SQL;` + static `_shipTo($table = self::TABLE)` returning a correlated subquery
   `SELECT Addresses.addressee FROM Addresses WHERE Addresses.id = $table.shipToAddressId`),

package/knowledge/2.0/apps/api2/features/nested-fk-acl-embedding.md

@@ -6,14 +6,17 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-23
-owners: [apeterson]
+updated: 2026-09-10
+owners: [apeterson, bala]
 files:
   - api2/Component/Api/V2/V2.php
   - dbchanges2/Client_Compass/2026-07-23b - PurchaseOrdersRecordReadAcl.sql
+  - dbchanges2/Client_Nychh/2026-09-09d - ApiRoleReadLocationAddress.sql
 related:
   - cross-client-data-retrieval.md
   - tableview-apiwhereclause-row-filtering.md
+  - v2-rest-query-contract.md
+  - ../../worker2/features/netsuite-transferorder-outbound-push.md
 ---
 
 ## What it is
@@ -59,6 +62,33 @@ a machine/API caller on role 3 sees it fine.
   ids), `NOT EXISTS`-guarded, wrapping any self-referencing subquery in a derived table to avoid MySQL
   error 1093. See `dbchanges2/Client_Compass/2026-07-23b - PurchaseOrdersRecordReadAcl.sql`.
 
+## ⚠ Deepening a `depth` expansion is an ACL change — check EVERY record it crosses
+
+The same silent drop bites when nothing about the ACL changed and only the **read shape** did.
+Raising `depth` pulls in records the old read never touched, and each new record needs its own
+`AclRecordPermissions` row **for the calling role** or that whole branch comes back empty — 200,
+`isSuccess: true`, no message.
+
+**Rule: before you raise a depth, list the records the new expansion crosses and confirm an ACL row
+exists for the role the caller actually authenticates as.** Service callers are the usual victims,
+because a developer testing in a browser holds different roles.
+
+**Confirmed case (2026-09-09, NYCHH transfer-order → NetSuite push).** Expanding the ship-to address
+from `order → destinationLocation` out to `… → primaryLocationAddress → address → state → country`
+crossed Core records **69 “Location addresses”**, **12 “States”** and **23 “Countries”**. The push
+reads `/transfer-orders` as role **3 “API”** (authenticating with the `Client_Nychh.Apis` row named
+`Agilant`), and `Client_Nychh.AclRecordPermissions` had **no roleId 3 row for any of the three** —
+only roleId **1 “Base”**. **Roles are looked up per `roleId` directly in
+`api2/Component/Api/V2/V2.php`; there is no Base-role inheritance**, so a role-1 grant does nothing
+for a role-3 caller. `Client_Compass` already carried role 3 on all three, which is why the identical
+read shape works there. Fixed with `Client_Nychh/2026-09-09d - ApiRoleReadLocationAddress.sql`
+(read-only role-3 rows for 69, 12, 23, `NOT EXISTS`-guarded).
+
+**Why this one was expensive:** without those rows the deeper read returns the same thing as the
+shallow read, so the code fix that motivated the depth change would have shipped as a **silent
+no-op** and looked like a code bug. Mechanics of that push are in
+[transfer-order → NetSuite push](../../worker2/features/netsuite-transferorder-outbound-push.md).
+
 ## Diagnostic tell
 
 A top-level GET of the child record **works** but the **nested embed of the same record under a
@@ -67,6 +97,15 @@ record's `AclRecordPermissions` for the caller's role — not the parent's grant
 permissions.
 
 ## Change history
+- 2026-09-09 — Added the **depth-expansion** face of this bug: raising `depth` crosses records the old
+  read never touched, and each one needs an `AclRecordPermissions` row **for the calling role** or the
+  branch is dropped silently. Confirmed on the NYCHH transfer-order → NetSuite push, where expanding
+  the ship-to address to depth 6 crossed Core records **69 Location addresses / 12 States / 23
+  Countries** and `Client_Nychh` had **no roleId 3 (“API”) row on any of them** — only roleId 1
+  (“Base”), which does not inherit, roles being resolved per `roleId` in `V2.php`. `Client_Compass`
+  already had role 3 on all three, which is why the same shape worked there. Fixed by
+  `Client_Nychh/2026-09-09d`; the durable rule is to audit ACL on every record a new expansion crosses
+  before assuming the deeper read is broken. (bala)
 - 2026-07-23 — Documented that V2 nested-FK embedding (`getFullModelData`) re-checks the CHILD
   record's own `AclRecordPermissions` and SILENTLY drops the nested object (200, isSuccess true, no
   message) when no grant exists — needing only an ACL row, not a logic-group expression. Fixed the
@@ -75,5 +114,3 @@ permissions.
   embedded fine; mirrored Quad's role-1 grant (`Client_Compass/2026-07-23b`). Confirmed this is the
   SAME role-3-vs-role-1 mis-seed pattern already seen on CompassCanada (record 275) — not
   CompassCanada-only. (apeterson)
-</content>
-</invoke>

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

@@ -7,6 +7,7 @@
 | [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 |
 | [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 |
 | [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 |
+| [Deleting Contacts rows from a client database (the FK order, and the self-referencing trap)](workflows/deleting-contacts-from-a-client-database.md) | Clearing test `Contacts` out of a 2.0 client database is **not** a one-line `DELETE`. |
 | [Framework branch running AHEAD of schema — environment-wide 1054/EO-1 after a deploy](workflows/framework-branch-ahead-of-schema.md) | A **third** kind of 2.0 schema drift, distinct from the two already documented: nobody's database went backwards — **the code went forwards**. |
 | [Local vs prod MySQL config parity — why “it passed locally” is not evidence](workflows/local-vs-prod-mysql-config-parity.md) | Several migration failures that look like "prod-only bugs" are actually **per-machine MySQL server-configuration differences**. |
 | [Repairing non-prod metadata drift (works in prod, broken in beta/dev-sandbox)](workflows/nonprod-metadata-drift-repair.md) | Almost all 2.0 platform behavior is **metadata** — `Core.Records`/`RecordFields`, `Core.RecordScripts`, `Core.ApiPayloadInterceptors`, and per-client `Acl*` row |

package/knowledge/2.0/apps/dbchanges2/workflows/deleting-contacts-from-a-client-database.md

@@ -0,0 +1,87 @@
+---
+title: "Deleting Contacts rows from a client database (the FK order, and the self-referencing trap)"
+framework: "2.0"
+repo: dbchanges2
+project: Database Changes
+client: shared
+type: workflow
+status: active
+updated: 2026-09-10
+owners: [bala]
+files:
+  - dbchanges2/Client_Nychh/2026-09-09a - DeleteTestContacts.sql
+  - dbchanges2/Client_Nychh/2026-09-09b - InsertDeliveryContacts.sql
+related:
+  - ../architecture.md
+  - ../features/rerunnable-additive-inserts.md
+  - ../../../clients/nychh/features/location-shipping-addresses.md
+---
+
+## Summary
+
+Clearing test `Contacts` out of a 2.0 client database is **not** a one-line `DELETE`. Nothing
+cascades, and `Contacts` points **back at its own children**, so the obvious order fails with
+`SQL Error [1451] ... Contacts_ibfk_1`. Verified on `Client_Nychh` 2026-09-09 while replacing 12
+test contacts with 19 real delivery contacts.
+
+**The two facts that cost the time:**
+
+1. **No foreign key referencing `Contacts` cascades.** 24 of them are `NO ACTION` and 5 are
+   `RESTRICT`, so **every child row must be cleared by hand**.
+2. **`Contacts` holds FKs pointing DOWN at its own children** — `Contacts_ibfk_1` →
+   `ContactEmailAddresses`, `Contacts_ibfk_2` → `ContactAddresses`, `Contacts_ibfk_3` →
+   `ContactPhoneNumbers`, through `primaryContactEmailAddressId` / `primaryContactAddressId` /
+   `primaryContactPhoneNumberId`. So the parent must **release** its children before they can be
+   deleted. Delete the email rows first and you get error 1451 on `Contacts_ibfk_1`.
+
+## Steps
+
+1. **Unlink the business rows that reference the contact.** For transfer orders that is
+   `UPDATE TransferOrders SET contactId = NULL WHERE contactId IN (…)`. Find the full set with
+   `information_schema.KEY_COLUMN_USAGE` against `REFERENCED_TABLE_NAME = 'Contacts'` — do not
+   assume the list.
+2. **NULL the three `primaryContact*Id` columns on `Contacts` first** (`primaryContactEmailAddressId`,
+   `primaryContactAddressId`, `primaryContactPhoneNumberId`). This is the step that is easy to miss.
+3. **Delete `Contacts_Locations`** for those contacts.
+4. **Delete `ContactEmailAddresses`, then `ContactPhoneNumbers`, then `ContactAddresses`.**
+5. **Delete `Contacts_Vendors`** — `Contacts_Vendors_ibfk_2` blocks the delete even when the table
+   holds no matching rows for these contacts.
+6. **Delete `Contacts`.**
+7. **`COMMIT`.**
+8. **Only then run `ALTER TABLE Contacts AUTO_INCREMENT = 1`.** `ALTER TABLE` performs an **implicit
+   commit**, so putting it inside the transaction ends the transaction early and the rollback safety
+   net is gone before the deletes are checked.
+
+## Re-seeding contacts — the shape that works
+
+Per person: one `Contacts` row, one `ContactEmailAddresses` row (`name = 'Work'`) set as the
+contact's `primaryContactEmailAddressId`, and one `Contacts_Locations` row with `type = 'SHIPPING'`
+per facility. **One contact can hold several `Contacts_Locations` rows** — the same person covering
+two sites is one contact with two links, not two contacts.
+
+- **`uuid` must be a real UUID4 literal in the file**, never MySQL `UUID()` (the standing 2.0 rule).
+- **`contactTypeId` is nullable and usually should stay NULL** — a client's `ContactTypes` table is
+  commonly empty (it is on `Client_Nychh`), and inventing a type row to fill the column is worse
+  than leaving it null.
+
+## Gotchas
+
+- **⚠ `SQL Error [1451] ... Contacts_ibfk_1` means the PARENT still points at the child.** It reads
+  like a normal child-blocks-parent error and it is the opposite. NULL the `primaryContact*Id`
+  columns, then retry.
+- **⚠ `ALTER TABLE` after `COMMIT`, always.** Same trap as any implicit-commit statement inside a
+  migration transaction.
+- **⚠ Do not assume the child list.** 29 constraints reference `Contacts` on a full client schema;
+  query `information_schema` for the database you are actually in, because client schemas drift
+  (see [client schema drift audit](./client-schema-drift-audit.md)).
+
+## Change history
+
+- 2026-09-09 — Wrote up the delete order after hitting `Contacts_ibfk_1` on `Client_Nychh` while
+  swapping 12 test contacts for 19 real delivery contacts. Recorded that **no FK on `Contacts`
+  cascades** (24 `NO ACTION`, 5 `RESTRICT`), that `Contacts` points **back** at
+  `ContactEmailAddresses` / `ContactAddresses` / `ContactPhoneNumbers` through its three
+  `primaryContact*Id` columns so those must be NULLed **before** the child rows are deleted, that
+  `Contacts_Vendors` blocks the delete regardless of content, and that
+  `ALTER TABLE … AUTO_INCREMENT = 1` must sit **after** `COMMIT` because it commits on its own.
+  (bala)

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-09-04
+updated: 2026-09-10
 owners: [apeterson, bala]
 files:
   - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateTransferOrder.ts
@@ -73,6 +73,7 @@ related:
   - ../../toga-blox/features/advanced-select.md
   - ../../toga-blox/features/primary-table-templates.md
   - ../../../standards/frontend.md
+  - ../../../../clients/nychh/features/location-shipping-addresses.md
 ---
 
 ## Summary
@@ -482,8 +483,26 @@ Verified on NYCHH 2026-09-01: exactly **1 of 31** active locations sets `allowRe
 **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.**
 
-The dropdown lists **all active locations minus the source**. Treat `allowReceiving` as a column
-nobody populates until someone proves otherwise per tenant.
+**The dropdown filters on `Locations.locationTypeId` instead (2026-09-10).**
+`hooks/useTargetLocationOptions.ts` now sends a second condition in the same `where` `and` array:
+
+```ts
+where: { and: [
+  { "Locations.isActive": { "=": "1" } },
+  { "Locations.locationTypeId": { "=": "1" } },
+] }
+// serializes to where=(Locations.isActive:eq:1,AND,Locations.locationTypeId:eq:1)
+```
+
+Before this it asked for every active location, so all **31** NYCHH active rows were offered,
+including the **7** internal/warehouse rows (Health & Hospitals, Health & Hospitals Processing, the
+New York warehouse, Bay S-A-01-A, Chicago, New York, New York HQ) — one of which is the **source
+warehouse the transfer ships FROM**. Verified on prod `Client_Nychh`: `locationTypeId` **1 = 24
+shipping locations** (hospitals/clinics), **2 = 7 warehouse/office rows**. So the location TYPE is
+the filter that actually works here, and `allowReceiving` is not. Live in production
+(commit `eb12055`, branch `_production`).
+
+Treat `allowReceiving` as a column nobody populates until someone proves otherwise per tenant.
 
 Related data-shape facts found the same day:
 
@@ -611,6 +630,14 @@ Wider platform finding from building them:
 - **Flat-list picker with debounced search.** The breadcrumb path is assembled from
   `parentLocation.uuid` **with a cycle guard** — a self- or mutually-parented row would otherwise
   loop forever.
+- **Only shipping locations are listed** — the `where` carries `Locations.locationTypeId = "1"`
+  alongside `isActive`; see [the `allowReceiving` section](#-allowreceiving-is-unmaintained--do-not-filter-the-target-dropdown-on-it).
+- **A location's own address IS the transfer's delivery address.** `TransferOrders` has no ship-to
+  column (only `originLocationId` / `destinationLocationId`), unlike `SalesOrders`, which carries
+  its own `shipToAddressId` per order. So a wrong `Locations` address is invisible on the sales-order
+  screens and shows up **only here** — exactly how NYCHH's 24 shipping locations were found all
+  rendering one head-office billing address:
+  [NYCHH location shipping addresses](../../../../clients/nychh/features/location-shipping-addresses.md).
 - **Target Contact options come from `Contacts` through the `Contacts_Locations` junction**, scoped
   to the selected location.
 - **`Locations` deliberately does NOT get a contact FK.** The junction is the right place, and it is
@@ -885,6 +912,14 @@ deliberate, separate exception — see [surface-frontend](./surface-frontend.md)
 
 ## Gotchas
 
+- **⚠ Never filter the target-location dropdown on `allowReceiving`, and never leave it
+  unfiltered either** — filter on `Locations.locationTypeId = "1"` (shipping). Unfiltered, the list
+  offers warehouses including the source of the transfer.
+- **⚠ `_addressState` returned the state's internal ID, not its code**, so a location address
+  rendered as `Bronx, 33 10451-5504`. Fixed in `_Model_Client_Location` by joining `States` and
+  selecting `States.code`; see
+  [FIELD_SQL calculated fields](../../_underscore/features/calculated-sql-fields.md). **Written but
+  NOT deployed as of 2026-09-10**, so the id still shows in production.
 - **⚠ 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.
 - **⚠ An ungranted `uuid` field 403s the WHOLE request** — `uuid` is V2's `IDENTIFIER_FIELD` and is
@@ -958,6 +993,18 @@ deliberate, separate exception — see [surface-frontend](./surface-frontend.md)
   earlier migration without names, so a name-based lookup on them finds nothing.
 
 ## Change history
+- 2026-09-10 — **Target Location dropdown now lists only shipping locations.**
+  `useTargetLocationOptions.ts` gained a second `where` condition,
+  `{ "Locations.locationTypeId": { "=": "1" } }`, so the serialized query is
+  `where=(Locations.isActive:eq:1,AND,Locations.locationTypeId:eq:1)`. It previously fetched every
+  active location, which put all **31** NYCHH rows in the list including the **7**
+  warehouse/office rows — one being the source warehouse the transfer ships from. Prod
+  `Client_Nychh` splits **24 shipping / 7 warehouse**, and `allowReceiving` remains unusable
+  (1 of 31, and it is the source). Committed and live in prod (`eb12055`, `_production`). Also
+  recorded that a transfer's delivery address comes from the LOCATION record (no ship-to column on
+  `TransferOrders`), which is why NYCHH's shared head-office address only broke this screen —
+  see [NYCHH location shipping addresses](../../../../clients/nychh/features/location-shipping-addresses.md).
+  (bala)
 - 2026-09-04 — **Virtualized the item picker, made the create POST set an opening stage, and lit up
   the status badge.** (1) `TransferItemPickerTable` now renders through `@tanstack/react-virtual`
   with the offsets as **spacer `<tr>`s inside the real `<table>`**, so `table-layout: fixed`, the

package/knowledge/2.0/apps/worker2/features/netsuite-transferorder-outbound-push.md

@@ -6,16 +6,18 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-09-08
+updated: 2026-09-10
 owners: ["bala"]
 files:
   - worker2/Worker/Netsuite/SalesOrder.php
   - _underscore/Model/Client/TransferOrder.php
   - dbchanges2/Client_Nychh/2026-09-02a - TransferOrderNetsuitePushInterceptor.sql
+  - dbchanges2/Client_Nychh/2026-09-09d - ApiRoleReadLocationAddress.sql
   - test/@Bala/tests/netsuite_transferorder_payload_tests.php
   - test/@Bala/tests/transferorder_interceptor_tests.php
 related:
   - ./netsuite-salesorder-outbound-push.md
+  - ../../api2/features/nested-fk-acl-embedding.md
   - ./creating-worker-actions.md
   - ../../api2/features/api-payload-interceptors.md
   - ../../api2/features/v2-rest-query-contract.md
@@ -45,6 +47,10 @@ re-read this doc if you last saw it on 2026-09-02: **the NetSuite customer is th
 destination location**, and `description` is now sent as the NetSuite **`memo`**. Committed as
 worker2 **`cbafd25`** on `_production` and deployed.
 
+**A third correction is written but NOT yet deployed (2026-09-09): the push was sending no ship-to
+address at all**, so NetSuite used the customer's default site on every order. That fix and the
+depth-6 read it needs are below.
+
 ## Key files / entry points
 
 | Action | Method | Purpose |
@@ -89,8 +95,8 @@ additive precedence change safe to reason about instead of hope.
 
 ## What is actually sent to NetSuite
 
-Nothing beyond this list. A transfer order has no shipping cost, ship method, terms, subsidiary,
-shipping address or status columns, so none are sent.
+Nothing beyond this list. A transfer order has no shipping cost, ship method, terms, subsidiary or
+status columns, so none are sent.
 
 | NetSuite field | Source |
 |---|---|
@@ -98,6 +104,7 @@ shipping address or status columns, so none are sent.
 | `tranDate` | `dateOrder`, date only; **omitted** when null |
 | `otherRefNum` | the PO number (the developer's explicit requirement) |
 | `memo` | `TransferOrders.description` — the NYCHH custom form renders it as **"ORDER DESCRIPTION"** |
+| `shippingAddress` | the **destination** Location's `primaryLocationAddress.address` (added 2026-09-09, not yet deployed). The key is **omitted** when the destination has no address, so NetSuite keeps its own default instead of getting an empty one. |
 | `externalId` | `toga-to-<transfer order uuid>` |
 | line `item` / `quantity` | each transfer-order item |
 | line `rate` | **0** — this is the zero-value part |
@@ -147,6 +154,62 @@ showed the transfer order's `description`.
 destination whose customer id already equals the client's own (**30205** and **36443**), so the old
 and new rules produce the same id for them.
 
+
+### ⚠ The ship-to address was NEVER sent — and it needs a depth-6 read (fixed 2026-09-09, not deployed)
+
+`buildSalesOrderShapeFromTransferOrder()` never set a `shipToAddress` key, and the `shippingAddress`
+block in `buildNetSuiteOrder()` (~L922) only runs when that key exists. So **every transfer order
+went to NetSuite with no address**, and NetSuite substituted the **customer's default shipping
+address**. Because the customer is now always the client (previous section), that default is one
+head-office site for **every** destination.
+
+Live evidence: NetSuite order **7467799** was for **North Central Bronx** in supply and shipped to
+*“1400 Pelham Parkway South, Bronx”* (**Jacobi**); SO **289187** (Woodhull) shows the same address.
+Both are the default on NetSuite customer **28908**. Grepped the whole file — there was no other
+place sending an address for a transfer order.
+
+**Fix:** new private `resolveTransferOrderShipToAddress(object $destinationLocation): ?object` reads
+`$destinationLocation->primaryLocationAddress->address`, and the shape sets `shipToAddress` only when
+it is non-null.
+
+> **Durable rule:** a transfer order's NetSuite customer is the client's *whole account*, so the
+> customer default can never be the right ship-to. The address must come from the **destination
+> Location**. This is the same “ships-where ≠ who-is-billed” split as the customer fix, one field later.
+
+#### The address sits TWO levels deeper than a sales order's
+
+| Order | Path to the country | Depth needed |
+|---|---|---|
+| sales order | `order → shipToAddress → state → country` | **4** (`TOGA_FETCH_DEPTH`, unchanged) |
+| transfer order | `order → destinationLocation → primaryLocationAddress → address → state → country` | **6** |
+
+At depth 4 the address comes back **missing with no error at all** — the max-depth omission rule in
+[V2 REST query contract](../../api2/features/v2-rest-query-contract.md). The order is read in **two**
+places, so **both** depths were raised:
+
+- `_Model_Client_TransferOrder::NETSUITE_READ_DEPTH` **4 → 6** — the `postPost` read done before
+  queueing. The order travels with the job, so this is the read that matters in practice.
+- new `TOGA_FETCH_DEPTH__TRANSFER_ORDER = 6` in the worker, chosen by the existing `$isTransferOrder`
+  flag in `fetchSalesOrder()` — the fallback path when no order is carried. **Sales orders still read
+  at 4.**
+
+Note this contradicts nothing above: `NETSUITE_READ_DEPTH` stays a class constant (not INI) for the
+same reason — it is a fact about the read shape, and the shape just got deeper.
+
+#### ⚠ Raising a depth is an ACL change, not just a number
+
+The new branch crosses three records the old read never touched — Core records **69 Location
+addresses**, **12 States**, **23 Countries** — and the push reads `/transfer-orders` as role **3
+“API”**. `Client_Nychh` had **no role-3 `AclRecordPermissions` rows for any of the three**, so the
+expanded branch would have come back empty, `resolveTransferOrderShipToAddress()` would have returned
+null, and the code fix would have been a **silent no-op**. Fixed by
+`dbchanges2/Client_Nychh/2026-09-09d - ApiRoleReadLocationAddress.sql`.
+
+> **Durable rule: when you deepen a `depth` expansion on any api2 read, check
+> `AclRecordPermissions` for the CALLING role on EVERY record the new expansion crosses.** A missing
+> row drops the branch silently instead of erroring — see
+> [nested FK ACL embedding](../../api2/features/nested-fk-acl-embedding.md).
+
 ### `description` → `memo` cannot leak into a plain sales order
 
 `memo` is sent only from the transfer-order shape. There is **no `memo` RecordField and no `memo`
@@ -300,6 +363,12 @@ Stub detail for anyone extending it: `_Model_True` is stubbed with **only** the
   `postPost` reads **zero lines** and the push aborts — the trigger would then have to move. See
   [Transfer Orders page](../../toga25-supply/features/transfer-orders-page.md).
 - **dev-sandbox metadata is incomplete** (record 325 + its RecordFields + both inherent-child rows).
+- **The ship-to fix is written, `php -l` clean, but NOT deployed and NOT committed** (worker2 +
+  `_underscore`). The two NYCHH SQL files it depends on **have** been run on prod.
+- **Undecided: should the delivery contact go into the NetSuite `attention` field?** NetSuite ship-to
+  addresses carry a person on the first line (order **289193** shows *Frederick Roberts*, the Bellevue
+  delivery contact). `TransferOrders.contactId` exists as an FK on `_Model_Client_TransferOrder` but
+  **nothing in worker2 or toga2-supply reads it** — nothing is wired, and nothing was decided.
 - **Undecided: disable the customer name-search fallback for transfer orders?**
   `resolveNetSuiteCustomerId()` falls back to a SuiteQL search by company **name** when the
   destination has no customer id, and NYCHH's `Health & Hospitals` vs `NYC Health + Hospitals` are
@@ -328,6 +397,21 @@ Stub detail for anyone extending it: `_Model_True` is stubbed with **only** the
 
 ## Change history
 
+- 2026-09-09 — **The push had never sent a shipping address at all.**
+  `buildSalesOrderShapeFromTransferOrder()` set no `shipToAddress` key, so the `shippingAddress` block
+  in `buildNetSuiteOrder()` never ran and NetSuite substituted the **customer's default** site on every
+  order — NetSuite order **7467799** (North Central Bronx) and SO **289187** (Woodhull) both shipped to
+  Jacobi's *1400 Pelham Parkway South*, the default on customer 28908. Added
+  `resolveTransferOrderShipToAddress()` reading `destinationLocation->primaryLocationAddress->address`,
+  set on the shape only when non-null so a destination with no address still lets NetSuite use its own
+  default. Discovered the address sits **two levels deeper than a sales order's** (order → destination
+  → primaryLocationAddress → address → state → country = **6**, versus 4), and at depth 4 it returns
+  **missing with no error**: raised `_Model_Client_TransferOrder::NETSUITE_READ_DEPTH` 4 → 6 and added
+  `TOGA_FETCH_DEPTH__TRANSFER_ORDER = 6` for the fallback fetch, sales orders unchanged at 4. Also
+  recorded the durable rule that **deepening a depth is an ACL change** — the new branch crosses Core
+  records 69/12/23 and `Client_Nychh` had no role-3 grant on any of them, which would have made the
+  whole fix a silent no-op (fixed by `Client_Nychh/2026-09-09d`). Code written and `php -l` clean but
+  **not deployed and not committed**. (bala)
 - 2026-09-08 — **Went live, and fixed the customer.** `buildSalesOrderShapeFromTransferOrder()` was
   sending the **destination Location** as the NetSuite customer, which put SO **7462031** on
   sub-customer **33674** (CHS) instead of **28908**; it only ever looked correct because almost every

package/knowledge/INDEX.md

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

package/knowledge/clients/nychh/INDEX.md

@@ -2,6 +2,7 @@
 
 | Doc | Framework | Summary |
 |-----|-----------|---------|
+| [NYCHH transfer-order destinations — location shipping addresses + delivery contacts](features/location-shipping-addresses.md) | 2.0 | Every one of NYCHH's **24 shipping locations** (`Locations.locationTypeId = 1`) resolved to the same address — **50 Water St., 3rd Floor, New York, NY 10004**, |
 | [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 |
 | [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_ |
 | [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 |

package/knowledge/clients/nychh/features/location-shipping-addresses.md

@@ -0,0 +1,150 @@
+---
+title: "NYCHH transfer-order destinations — location shipping addresses + delivery contacts"
+framework: "2.0"
+repo: dbchanges2
+project: Database Changes
+client: nychh
+type: client-feature
+status: active
+updated: 2026-09-10
+owners: [bala]
+files:
+  - dbchanges2/Client_Nychh/2026-09-09c - UpdateLocationShippingAddresses.sql
+  - dbchanges2/Client_Nychh/2026-09-09a - DeleteTestContacts.sql
+  - dbchanges2/Client_Nychh/2026-09-09b - InsertDeliveryContacts.sql
+  - _underscore/Model/Client/Location.php
+  - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTargetLocationOptions.ts
+related:
+  - ../profile.md
+  - ./netsuite-transfer-order-import.md
+  - ./transfer-order-netsuite-push.md
+  - ../../../2.0/apps/toga25-supply/features/transfer-orders-page.md
+  - ../../../2.0/apps/_underscore/features/calculated-sql-fields.md
+  - ../../../2.0/apps/dbchanges2/workflows/deleting-contacts-from-a-client-database.md
+  - ../../../2.0/apps/worker2/features/netsuite-transferorder-outbound-push.md
+---
+
+## Summary
+
+Every one of NYCHH's **24 shipping locations** (`Locations.locationTypeId = 1`) resolved to the same
+address — **50 Water St., 3rd Floor, New York, NY 10004**, attention *"Accounts Payable OTPS"*. That
+is the head-office **Accounts Payable BILLING** address, not a delivery address, so the Create
+Transfer Order target-location list showed one identical address 24 times and a transfer had no real
+delivery address. Fixed 2026-09-09 by backfilling each location's own **NetSuite default shipping
+address**.
+
+The load-bearing fact behind the whole issue: **for NYCHH a `Locations` address only affects transfer
+orders.** `SalesOrders` carries its own `shipToAddressId` per order and those already held the real
+hospital addresses (462 1st Ave, 451 Clarkson Ave, 100 N Portland Ave, …). `TransferOrders` has **no
+ship-to column at all** — only `originLocationId` / `destinationLocationId` — so a transfer's
+delivery address is read off the location record. That is why a wrong location address was invisible
+everywhere except the transfer screen.
+
+## How it works — where a location's shipping address comes from
+
+- Each `Locations` row points at its own `Addresses` row through `Locations_Addresses`. The rows
+  **existed** (`Addresses` ids **261–303**); they simply all held the same values, so this was a
+  data problem, not a missing-topology problem.
+- The source of truth is the location's **NetSuite customer** record:
+  `Locations.c_netsuiteInternalCustomerId` → `customer` → `customerAddressbook` with
+  **`defaultshipping = 'T'`**. (On a NYCHH transfer order the destination location is the NetSuite
+  *customer* and the origin is the NetSuite *warehouse* — see
+  [transfer-order NetSuite push](./transfer-order-netsuite-push.md).)
+- `attention` belongs on a **bill-to**, not a ship-to. The backfill cleared it, because it carried
+  *"Accounts Payable"* on rows now used as delivery addresses.
+
+## The migration — `Client_Nychh/2026-09-09c - UpdateLocationShippingAddresses.sql`
+
+1. **UPDATE 23 existing `Addresses` rows in place** with the NetSuite default-shipping values.
+2. **INSERT one new row** for location **2 "NYC Health + Hospitals"** and repoint
+   `Locations_Addresses.id = 24` at it, because that location was **sharing `Addresses.id = 1` with
+   location 1 (Lincoln)** — updating the shared row would have silently changed Lincoln too.
+3. Clear `attention`.
+
+**Why overwriting in place was safe:** verified that **no** `SalesOrders`, `PurchaseOrders`,
+`ItemFulfillments`, `AdvanceShippingNotices`, `ServiceRequests` or `Customers` row pointed at any of
+those `Addresses` ids. Do that check before reusing an `Addresses` row anywhere — an `Addresses` row
+is shareable, so an in-place UPDATE is a multi-record edit until proven otherwise.
+
+**Applied and verified in production 2026-09-09.** All 24 locations now carry their own street, city
+and zip: **22 distinct addresses across 24 locations**, and both repeats are real per NetSuite
+(Harlem + Renaissance at 506 Lenox Ave; Jacobi + NYC Health + Hospitals at 1400 Pelham Parkway
+South).
+
+## Delivery contacts — 12 test rows replaced with 19 real people (2026-09-09)
+
+The same Create Transfer Order screen picks a **Target Contact** from `Contacts` through the
+**`Contacts_Locations`** junction, scoped to the chosen location. `Client_Nychh` held **12 test
+contacts**; they were deleted and **19 real NYCHH delivery contacts** inserted (ids **1–19**, **18**
+location links) by `2026-09-09a - DeleteTestContacts.sql` and `2026-09-09b - InsertDeliveryContacts.sql`.
+
+- Shape per person: one `Contacts` row, one `ContactEmailAddresses` row (`name = 'Work'`) set as
+  `primaryContactEmailAddressId`, and a `Contacts_Locations` row with `type = 'SHIPPING'`.
+- **Omar Moharem covers two facilities** (Dr. Susan Smith McKinney and Kings County) — **one** contact
+  with **two** `Contacts_Locations` rows, not two contacts. That is why 19 contacts produce 18 links
+  alongside the two people below who have none.
+- `Client_Nychh.ContactTypes` is **empty**, so `contactTypeId` is left NULL.
+- **Deleting the old rows was the hard part** — nothing cascades and `Contacts` points back at its own
+  children. The full order is in
+  [deleting Contacts from a client database](../../../2.0/apps/dbchanges2/workflows/deleting-contacts-from-a-client-database.md).
+
+## Open questions / known bad data
+
+- **🚩 OPEN — two contacts have no location link.** **Erald Velmishi** (Central Office) and **Harry
+  Ho** (Community Care) got no `Contacts_Locations` row because **neither facility exists in
+  `Locations`**. They will not appear in the Target Contact dropdown anywhere until the locations are
+  created.
+- **🚩 OPEN — nothing reads the chosen contact.** `TransferOrders.contactId` is a real FK on
+  `_Model_Client_TransferOrder`, but **no code in worker2 or toga25-supply reads it**. NetSuite
+  ship-to addresses do carry a person on the first line (order **289193** shows *Frederick Roberts*,
+  the Bellevue delivery contact), so wiring the contact into the NetSuite `attention` field is the
+  obvious next step — **undecided, not implemented**. See
+  [transfer-order → NetSuite push](../../../2.0/apps/worker2/features/netsuite-transferorder-outbound-push.md).
+
+- **🚩 OPEN — is location 2 "NYC Health + Hospitals" a real delivery place?** It is the destination
+  on **1,832 of 1,939** NYCHH transfer orders (next highest is Coney Island at 27), so it behaves as
+  a **catch-all destination**. But every one of those 1,832 has `createdByUserId` **NULL** — not one
+  was created by a person on the Create Transfer Order screen. They come from the automated NetSuite
+  import (277 on 2026-08-29, 1,528 on 2026-08-30, then 1–3/day). Its address was set to NetSuite's
+  value (**1400 Pelham Parkway South, Bronx NY 10461**) at the developer's direction, but that is
+  **Jacobi Medical Center's** address. Still with the project manager: is this a real receiving
+  place, or should the import pick the actual hospital instead? **Do not treat its address as
+  settled**, and see [the NetSuite transfer-order import](./netsuite-transfer-order-import.md).
+- **⚠ Two locations carry NetSuite customer ids that no longer exist.** **Bellevue Hospital Center →
+  29275** and **Jacobi Medical Center → 31917**; neither id is in the NetSuite `customer` table, so
+  their addresses came from other sources rather than a `defaultshipping` row. The ids need
+  correcting; until then any NetSuite lookup keyed on them returns nothing.
+
+## Gotchas
+
+- **⚠ A location's address surfaces ONLY on transfer orders for this client.** Sales orders carry
+  their own `shipToAddressId`, so "the address is fine on the order screens" says nothing about the
+  location record.
+- **⚠ An `Addresses` row can be shared by several locations** (ids 1 and 2 shared `Addresses.id = 1`
+  here). Always check before an in-place UPDATE; insert + repoint the junction instead.
+- **⚠ `attention = "Accounts Payable OTPS"` is the tell that a row is a BILL-TO** being used as a
+  ship-to. If a whole tenant's locations share one address, suspect the head-office AP address.
+- **⚠ The state renders as a number until `_addressState` ships.** The fixed
+  `_Model_Client_Location::_addressState()` (join `States`, select `States.code`) is written but
+  **not deployed**, so production still shows `Bronx, 33 10451-5504`. See
+  [FIELD_SQL calculated fields](../../../2.0/apps/_underscore/features/calculated-sql-fields.md).
+
+## Change history
+
+- 2026-09-09 — Replaced the **12 test contacts** with **19 real delivery contacts** (ids 1–19, 18
+  `Contacts_Locations` `SHIPPING` links; Omar Moharem covers two facilities on one contact), each with
+  a `'Work'` `ContactEmailAddresses` row as `primaryContactEmailAddressId` and `contactTypeId` NULL
+  because `ContactTypes` is empty. The delete needed a specific FK order —
+  [written up separately](../../../2.0/apps/dbchanges2/workflows/deleting-contacts-from-a-client-database.md).
+  Left open: Erald Velmishi and Harry Ho have no location link (their facilities do not exist in
+  `Locations`), and `TransferOrders.contactId` is still read by nothing. (bala)
+- 2026-09-10 — Recorded the backfill and the surrounding facts. All **24** `locationTypeId = 1`
+  locations shared the head-office AP billing address (50 Water St), so
+  `Client_Nychh/2026-09-09c - UpdateLocationShippingAddresses.sql` pulled each location's NetSuite
+  `defaultshipping` address, UPDATEd 23 `Addresses` rows in place, INSERTed one for location 2 (it
+  was sharing `Addresses.id = 1` with Lincoln) and cleared `attention`. Applied and verified in
+  prod: 22 distinct addresses over 24 locations. Also captured that a location address drives
+  **transfer orders only** (`TransferOrders` has no ship-to column), the open question about
+  catch-all destination location 2 (1,832 of 1,939 transfers, all `createdByUserId` NULL, address
+  currently Jacobi's), and the two dead NetSuite customer ids (Bellevue 29275, Jacobi 31917).
+  (bala)

package/knowledge/clients/nychh/features/netsuite-transfer-order-import.md

@@ -6,7 +6,7 @@ project: Library
 client: nychh
 type: client-feature
 status: active
-updated: 2026-09-08
+updated: 2026-09-10
 owners: [jcardinal, bala, rgirish]
 files:
   - library/app/api/toga2.php
@@ -29,6 +29,7 @@ related:
   - ./transfer-order-inventory-quantities.md
   - ./transfer-order-netsuite-push.md
   - ../../../2.0/apps/worker2/features/netsuite-transferorder-outbound-push.md
+  - ./location-shipping-addresses.md
   - ../profile.md
 ---
 
@@ -286,6 +287,13 @@ item receipts replays about two years unless it is rewound forward first.
 
 ## Gotchas / known issues
 
+- **🚩 The import sends almost everything to catch-all destination location 2 "NYC Health +
+  Hospitals" — 1,832 of 1,939 transfer orders**, next highest Coney Island at 27, and **every one
+  has `createdByUserId` NULL** (277 on 2026-08-29, 1,528 on 2026-08-30, then 1–3/day). Whether that
+  location is a real receiving place or the import should resolve the actual hospital is **open with
+  the PM**; its address is currently Jacobi's. Do not assume the destination is correct:
+  [NYCHH location shipping addresses](./location-shipping-addresses.md).
+
 - **Real-TrnfrOrd item receipts are disabled — see the DEFERRED section above.** A receipt whose
   `createdFrom` is a real Transfer Order is skipped by design; do not read that as the importer being
   broken.
@@ -307,6 +315,11 @@ item receipts replays about two years unless it is rewound forward first.
 
 ## Change history
 
+- 2026-09-10 - Recorded that the import concentrates **1,832 of 1,939** transfer orders on catch-all
+  destination **location 2**, all with `createdByUserId` NULL (so none came from the Create Transfer
+  Order screen), and that whether it should resolve the real hospital instead is still open with the
+  PM. Cross-linked the location-address backfill. (bala)
+
 - 2026-09-08 - **Closed transfer orders never reached the Closed stage** - the `status === 'Closed'`
   `continue` in `common_sync_togasupply.php` (~L746) runs before the `isTransferOrder()` branch, so
   `syncTransferOrderFromNetsuite`'s `case 'Closed'` was dead code and **18 NYCHH transfer orders sat

package/knowledge/clients/nychh/features/transfer-order-netsuite-push.md

@@ -6,18 +6,21 @@ project: _Underscore
 client: nychh
 type: client-feature
 status: active
-updated: 2026-09-08
+updated: 2026-09-10
 owners: ["bala"]
 files:
   - _underscore/Model/Client/TransferOrder.php
   - worker2/Worker/Netsuite/SalesOrder.php
   - dbchanges2/Client_Nychh/2026-09-02a - TransferOrderNetsuitePushInterceptor.sql
+  - dbchanges2/Client_Nychh/2026-09-09d - ApiRoleReadLocationAddress.sql
   - test/@Bala/tests/netsuite_transferorder_payload_tests.php
 related:
   - ../../../2.0/apps/worker2/features/netsuite-transferorder-outbound-push.md
   - ../../../2.0/apps/api2/features/api-payload-interceptors.md
   - ../../../2.0/apps/dbchanges2/workflows/nonprod-metadata-drift-repair.md
+  - ../../../2.0/apps/api2/features/nested-fk-acl-embedding.md
   - ./netsuite-transfer-order-import.md
+  - ./location-shipping-addresses.md
   - ./po-number-upstream-direction.md
   - ../profile.md
 ---
@@ -91,6 +94,42 @@ from `TransferOrders.description` (now sent as NetSuite `memo`, a NYCHH custom-f
 So the location-role table above describes **which column a location carries**, not what gets sent
 as `entity`. Destination is still what resolves the *ship-to*; it is no longer the customer.
 
+## ⚠ `Client_Nychh` was missing the role-3 ACL rows the ship-to address needs (fixed 2026-09-09)
+
+The push now sends a ship-to address taken from the destination Location, which needs a **depth-6**
+read (`order → destinationLocation → primaryLocationAddress → address → state → country`) — mechanics
+in [the shared push doc](../../../2.0/apps/worker2/features/netsuite-transferorder-outbound-push.md).
+**That deeper read was dead on arrival for NYCHH.**
+
+The push reads `/transfer-orders` as **roleId 3 “API”**, authenticating with the `Client_Nychh.Apis`
+row named **`Agilant`**. `Client_Nychh.AclRecordPermissions` had **no roleId 3 row** for Core records
+**69 “Location addresses”**, **12 “States”** or **23 “Countries”** — only roleId **1 “Base”**. Roles
+are resolved per `roleId` in `api2/Component/Api/V2/V2.php`; **there is no Base-role inheritance**, so
+role 1 grants nothing to a role-3 caller. `Client_Compass` already carried role 3 on all three, which
+is why the identical read shape works there.
+
+**Without those rows the expanded address never comes back, the new helper returns null, and no
+address is sent — exactly the broken behaviour the code fix was meant to end.**
+
+Fixed by `dbchanges2/Client_Nychh/2026-09-09d - ApiRoleReadLocationAddress.sql` (read-only roleId 3
+rows for records 69, 12, 23, `NOT EXISTS`-guarded). **Run on prod and verified: role 3 now has
+`allowRead` on records 11, 12, 13, 23, 69.**
+
+> Generalised on [nested FK ACL embedding](../../../2.0/apps/api2/features/nested-fk-acl-embedding.md):
+> deepening a `depth` is an ACL change, and the branch is dropped **silently**.
+
+## Where the ship-to address comes from — and the location-2 problem
+
+The address is the **destination Location's** `primaryLocationAddress.address`. Until 2026-09-09 all
+**24** NYCHH shipping locations shared the head-office Accounts Payable billing address, so even a
+correct push would have shipped everything to 50 Water Street; that backfill and its open questions
+are in [location shipping addresses + delivery contacts](./location-shipping-addresses.md).
+
+**Still open and still wrong for the push:** `Locations.id = 2` “NYC Health + Hospitals” carries
+`Addresses.id 32536` = **1400 Pelham Parkway South**, which is **Jacobi's** address, not a real
+delivery site for that location — and location 2 is the destination on the large majority of NYCHH
+transfer orders. Any transfer order to location 2 will ship to Jacobi.
+
 ## Interceptor registration — record 312, and the deploy order matters
 
 `dbchanges2/Client_Nychh/2026-09-02a - TransferOrderNetsuitePushInterceptor.sql` inserts into
@@ -125,6 +164,17 @@ switch that turns the feature on for NYCHH and nobody else.
 
 ## Change history
 
+- 2026-09-09 — **The push had never sent a shipping address**, so NetSuite used customer 28908's
+  default site on every order: NetSuite order **7467799** was for North Central Bronx yet shipped to
+  Jacobi's *1400 Pelham Parkway South*, and SO **289187** (Woodhull) shows the same. The fix reads the
+  destination Location's `primaryLocationAddress.address`, which needs a **depth-6** read — and that
+  read was **dead on arrival for NYCHH**: `Client_Nychh.AclRecordPermissions` had **no roleId 3
+  (“API”) row** for Core records **69 Location addresses / 12 States / 23 Countries**, only roleId 1
+  (“Base”), which does not inherit. `Client_Compass` already had role 3 on all three. Added them with
+  `2026-09-09d - ApiRoleReadLocationAddress.sql` — **run on prod, role 3 now reads records 11, 12, 13,
+  23, 69.** The worker2 / `_underscore` code side is written and `php -l` clean but **not deployed and
+  not committed**. Also noted that location **2** still holds Jacobi's address, so transfers to the
+  catch-all destination will ship to the wrong hospital. (bala)
 - 2026-09-08 — **First real order pushed (SO 289187 / id 7463537), and the customer was wrong until
   the same day.** The destination location was being sent as the NetSuite customer, which put SO
   **7462031** on sub-customer **33674** (CHS) instead of **28908** — `Locations` 1–26 are "Shipping"

package/knowledge/clients/nychh/profile.md

@@ -18,7 +18,7 @@ project: _Underscore
 client: nychh
 type: profile
 status: active
-updated: 2026-09-09
+updated: 2026-09-10
 owners: ["jcardinal", "apeterson", "bala", "akhokhani"]
 files:
   - dbchanges2/Client_Nychh/2026-09-02a - TransferOrderNetsuitePushInterceptor.sql
@@ -32,7 +32,10 @@ files:
   - dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql
   - dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql
   - dbchanges2/Client_Nychh/2026-09-02a - TalosAssistantEnable.sql
+  - dbchanges2/Client_Nychh/2026-09-09c - UpdateLocationShippingAddresses.sql
 related:
+  - ./features/location-shipping-addresses.md
+  - ../../2.0/apps/dbchanges2/workflows/deleting-contacts-from-a-client-database.md
   - ../../2.0/apps/_underscore/features/tracking-number-bridges.md
   - ../../2.0/apps/_underscore/features/tableview-joins.md
   - ./features/po-number-upstream-direction.md
@@ -44,6 +47,7 @@ related:
   - ./features/talos-assistant-enablement.md
   - ../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md
   - ../../2.0/apps/toga25-supply/features/transfer-orders-page.md
+  - ./features/location-shipping-addresses.md
 ---
 
 ## Summary
@@ -58,6 +62,17 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   run the NetSuite→TOGa Supply sync and the asset-tag verification/backfill diagnostics.
 
 ## Key features (this client)
+- **All 24 shipping locations shared ONE address until 2026-09-09 — the head-office Accounts
+  Payable bill-to (50 Water St).** Each location did have its own `Addresses` row (261-303); the
+  rows just held identical values, and locations 1 + 2 shared `Addresses.id = 1`.
+  `Client_Nychh/2026-09-09c - UpdateLocationShippingAddresses.sql` backfilled each from its NetSuite
+  customer's `defaultshipping` address (applied + verified in prod: 22 distinct addresses over 24
+  locations). It only ever showed on the **transfer-order** screens, because `TransferOrders` has no
+  ship-to column while `SalesOrders` carries its own `shipToAddressId`. 🚩 Still open: catch-all
+  destination **location 2 "NYC Health + Hospitals"** (1,832 of 1,939 transfers, all
+  `createdByUserId` NULL) currently holds **Jacobi's** address, and Bellevue/Jacobi carry NetSuite
+  customer ids (29275 / 31917) that no longer exist. See
+  [NYCHH location shipping addresses](./features/location-shipping-addresses.md).
 - 🚨 **sandbox-client (`Core` + `Client_Nychh`) was reset from PRODUCTION again on 2026-09-04** —
   the second reset in two days (the first, 2026-09-03, was over the stale `purchase-orders`
   TableView). Every "verified on <date>" sandbox-client claim in this profile dated **before
@@ -267,9 +282,11 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   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).
+  locations minus the source. The populated contact join is **`Contacts_Locations`** (record 76),
+  not `Locations_Contacts`; contacts were sparse until 2026-09-09, when 12 test rows were replaced by
+  **19 real delivery contacts** (18 location links). See
+  [Transfer Orders page](../../2.0/apps/toga25-supply/features/transfer-orders-page.md) and
+  [location shipping addresses + delivery contacts](./features/location-shipping-addresses.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/package.json

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