toga-ai 1.0.726 → 1.0.728

package/knowledge/2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-15
+updated: 2026-09-01
 owners: ["bala"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -14,6 +14,7 @@ files:
   - toga2-supply/src/api/toga.ts
 related:
   - ../../../clients/compass-usa/features/item-fulfillment-tracking-tableview.md
+  - ../../../clients/compass-usa/features/item-catalogs-and-duplicate-items.md
   - tableview-field-metadata.md
 ---
 
@@ -36,8 +37,9 @@ view with a migration and no application code.
 - **Consumption** — `toga2-supply/src/api/toga.ts` (~line 943-951): pushes the `apiWhereClause`
   literal string into `options.where.and`, and (~line 631-641) builds `options.join` / `ojoin`
   from the view's `TableViewJoins`.
-- **Parsing** — `api2/Component/Api/V2/V2.php::parseOptionsWhere` (~line 7574-7773): turns the
-  clause string into SQL.
+- **Parsing** — `api2/Component/Api/V2/V2.php::parseOptionsWhere` (~line 8200-8390, re-located
+  2026-09-01; it was ~7574 when this doc was first written, so search for the function name rather
+  than trusting the line number): turns the clause string into SQL.
 
 ## How it works
 
@@ -68,6 +70,22 @@ The field slot accepts a **raw SQL expression**, not just a plain column — e.g
 exclusion on the Compass fulfillment view): `(IFNULL(Items.assetTypeId,0):ne:<FEE id>)` — the
 `IFNULL(...,0)` keeps rows with a NULL FK from being silently dropped.
 
+### A single-condition clause is wrapped in parens too
+
+`parseOptionsWhere` **strips one leading `(` and one trailing `)` from the whole clause before it
+scans for top-depth commas** (V2.php ~line 8222-8229). Those outer parens are the group wrapper,
+not part of the first condition, so the house form for a one-condition filter is:
+
+```
+(Items.catalogId:eq:1)
+```
+
+The wrapper comes off first, leaving `Items.catalogId:eq:1`, which is then read as a plain
+condition — it is never mistaken for a nested group needing recursion. Write the parens; they match
+the existing Compass convention and the stored clauses stay uniform whether they hold one condition
+or five. (The "expression field must not start with `(`" gotcha below is about the *field slot* of a
+condition **after** the wrapper is removed — the two are not in conflict.)
+
 ### Join alias rule (which table-qualified name to use)
 
 In `_underscore/Model/Client/TableView.php` (~line 89-96), the **first** occurrence of a joined
@@ -77,6 +95,19 @@ referencing `Items.<field>` only binds correctly when the view joins `Items` **e
 Before writing a clause, confirm the target table is joined once, or qualify against the correct
 suffixed alias.
 
+**A view's base record is not a join, so it never gets a suffix.** Worked example — the shared
+`items` view (`TableViews.slug = 'items'`, `id 9`, `recordId 21` = `_Model_Client_Item`, route
+`items`; the same shape in `Client_Compass`, `Client_CompassCanada` and `Client_Quad`). Its four
+`TableViewJoins` are `joinRecordId` **20** Manufacturers, **33** ItemTypes, **32** AssetTypes and
+**34** ItemCategories, all INNER. `Items` appears only as the base record and is never re-joined,
+so the bare `Items.` qualifier is correct and there is no `_B`/`_C` to worry about. Check this the
+same way on any view before writing a clause: list the view's `TableViewJoins` and count how many
+resolve to the table you want to filter.
+
+Two schema notes for anyone writing the migration: `TableViews` has **no `name` or `tableName`
+column** in these client schemas — identify a view by its `slug` (UNIQUE) plus `recordId`, which is
+what makes `WHERE slug = 'items'` a safe, id-agnostic target across tenants.
+
 ## Data model
 
 - `TableViews.apiWhereClause` (TEXT, nullable) — the view-level row filter.
@@ -91,6 +122,8 @@ None — engine behavior. A specific client's view may carry its own `apiWhereCl
 
 - **Comma inside a function is safe.** The parser only splits conditions on top-depth commas, so
   a comma inside `IFNULL(x,0)` or `IN(...)` does not break the clause.
+- **A one-condition clause still needs its outer parens** — they are stripped before parsing, so
+  `(Field:eq:value)` and `Field:eq:value` behave identically; use the wrapped form for consistency.
 - **An expression field must NOT start with `(`.** A condition that starts with `(` is treated by
   the parser as a nested group and recursed into — so wrap an expression field in a function that
   starts with a letter (e.g. `IFNULL(...)`), never a bare parenthesized expression.
@@ -102,6 +135,15 @@ None — engine behavior. A specific client's view may carry its own `apiWhereCl
 
 ## Change history
 
+- 2026-09-01 — Recorded that the parser **strips one leading `(` and one trailing `)` from the whole
+  clause before splitting**, so the wrapped single-condition form `(Items.catalogId:eq:1)` is safe
+  and is the house convention (this was previously only documented for the multi-condition form).
+  Added a worked alias-verification example on the shared `items` view (id 9, recordId 21, four
+  INNER `TableViewJoins` 20/33/32/34, `Items` only as base record → bare `Items.` qualifier), noted
+  that `TableViews` carries no `name`/`tableName` column so `slug` is the id-agnostic target, and
+  re-pointed `parseOptionsWhere` at its current location (~8200, was ~7574). No code change —
+  verified while writing the catalog-1 filter migration for the `items` view in `Client_Compass`,
+  `Client_CompassCanada` and `Client_Quad`. (bala)
 - 2026-07-15 — Documented the end-to-end `apiWhereClause` row-filter mechanism (emission →
   consumption → `parseOptionsWhere` grammar), the operator→SQL table, the raw-expression field
   slot, the leading-paren / top-depth-comma parser behavior, and the `_underscore` join-alias

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

@@ -196,4 +196,12 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   numbers — because it does **not** use NetSuite, so it never hit the inventory-adjustment
   dupe-item bug that fed the merge. The catalog-fold damage and reversal were Compass USA only.
   See [Compass USA catalog-fold reversal](../compass-usa/workflows/catalog-fold-reversal.md).
+- **Items listing being filtered to catalog 1 (written 2026-09-01, NOT yet applied).** A migration
+  sets `TableViews.apiWhereClause = '(Items.catalogId:eq:1)'` on `Client_CompassCanada`'s shared
+  `items` view (`slug = 'items'`, id 9, recordId 21), alongside the same change in `Client_Compass`
+  and `Client_Quad`. **Canada is the harmless case today** — Canada has a **single catalog**
+  ("compass", see the bullet above), so every `Client_CompassCanada.Items` row is already catalog 1 and so the filter changes nothing visible now; it only pins the listing so a
+  future non-catalog-1 item (e.g. anything a NetSuite-style sync creates) would silently not appear.
+  Mechanism: [TableView apiWhereClause row-filtering](../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md);
+  catalog background: [Compass item catalogs](../compass-usa/features/item-catalogs-and-duplicate-items.md).
 - Related: [Compass USA](../compass-usa/profile.md).

package/knowledge/clients/compass-usa/features/item-catalogs-and-duplicate-items.md

@@ -17,6 +17,7 @@ files:
   - worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php
 related:
   - odp-edi-850-item-resolution.md
+  - ../../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md
   - mits-po-to-so-item-linking.md
   - mits-sales-order-transmission-alerting.md
   - isfulfillable-data-quality-and-type-rule.md
@@ -132,6 +133,32 @@ Plus `-1` / `-2` suffixed copies: items **2431, 2432, 2443, 2653**.
   (e.g. the `#B1H` / `-S` variant forms above) or genuinely-shared ones before treating table-wide
   `partNumber` uniqueness as settled.
 
+## Filtering by catalog: fine for *display*, never for *resolution*
+
+The blanket rule below ("never scope a Compass item lookup to one catalog") is about **resolving a
+part number to a record** — order import, PO→SO linking, vendor-item matching. It does **not** mean
+a catalog filter is banned everywhere. A **listing** is the legitimate exception: showing a user
+only the customer-facing Compass catalog is a product decision, and nothing downstream re-resolves
+off that list.
+
+**In flight as of 2026-09-01 (SQL written, NOT yet applied):** the shared TOGa Supply `items` table
+view (`TableViews.slug = 'items'`, `id 9`, `recordId 21`) is being restricted to catalog 1 by
+setting `TableViews.apiWhereClause = '(Items.catalogId:eq:1)'` — one `UPDATE … WHERE slug = 'items'`
+per schema, in `Client_Compass`, `Client_CompassCanada` **and** `Client_Quad` (the same view exists
+with the same id/recordId in all three). No application code changes; the mechanism is
+[TableView row-filtering via apiWhereClause](../../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md).
+The migration was written as a loose `items_tableview_catalog_filter_2026-09-01.sql` in the
+workspace root and handed to a developer to run (the DB tooling is read-only) — it still needs to
+land in `dbchanges2/Client_<schema>/` under the mandatory `YYYY-MM-DD<letter> - Name.sql` filename
+before it is a real change-set.
+
+**Open decision on the clause, and it is the NULL question again.** `Items.catalogId` is nullable in
+all three schemas, so a bare `:eq:1` silently drops the NULL-catalog items (a real, non-trivial
+population here — see the gotcha below, and it is proportionally much larger in `Client_Quad`). If
+those items must stay visible in the listing, the clause has to be
+`(IFNULL(Items.catalogId,1):eq:1)` instead. Decide before applying; the two forms are not
+interchangeable.
+
 ## "Who changed this part number?" — the audit trail says nobody
 
 The reflex answer to a part number that looks edited is to hunt for the person who edited it. For
@@ -151,9 +178,10 @@ children" rule:
 
 ## Gotchas
 
-- **⚠ Never scope a Compass item lookup to one catalog** unless you have proved the item can only
-  come from that source. The correct default is `Items.partNumber IN (...)` with **no** catalog
-  condition, and then reference the resolved record **by `uuid`**. **The catalog filter never buys
+- **⚠ Never scope a Compass item *lookup* to one catalog** unless you have proved the item can only
+  come from that source. (A read-only **listing** filter is the one sanctioned exception — see
+  [Filtering by catalog](#filtering-by-catalog-fine-for-display-never-for-resolution) above.) The
+  correct default is `Items.partNumber IN (...)` with **no** catalog condition, and then reference the resolved record **by `uuid`**. **The catalog filter never buys
   uniqueness on Compass** — `Items.partNumber` is unique across the whole table (re-verified prod
   2026-09-01) — so every catalog condition is pure downside.
 - **⚠ The 2.0 side hardcodes the OTHER catalog, and it broke MR purchase orders.**
@@ -193,6 +221,14 @@ children" rule:
   **unresolved tension**: that reversal folded/restored 199 catalog-1 items by `UPPER(partNumber)`,
   which implies shared cross-catalog part numbers pre-merge and does not square with the same-day
   "partNumber is unique table-wide" verification — needs a prod re-check. (jcardinal)
+- 2026-09-01 — Split the catalog-filter rule into **display vs. resolution**: the "never scope to one
+  catalog" ban covers part-number *resolution*, while a read-only *listing* filter is sanctioned.
+  Recorded the in-flight (written, **not yet applied**) change setting
+  `TableViews.apiWhereClause = '(Items.catalogId:eq:1)'` on the shared `items` view
+  (`slug = 'items'`, id 9, recordId 21) in `Client_Compass`, `Client_CompassCanada` and
+  `Client_Quad`, and the open decision it carries: `Items.catalogId` is nullable, so bare `:eq:1`
+  hides NULL-catalog items and `IFNULL(Items.catalogId,1):eq:1` is the alternative. Migration still
+  needs moving into `dbchanges2/Client_<schema>/`. (bala)
 - 2026-09-01 — Recorded a **second, independent victim of the same catalog-scoping trap, on the 2.0
   side**: `_Model_Compass_PurchaseOrder::handleMrOrder` references MR sales-order items with a
   hardcoded `COMPASS_CATALOG_UUID` (`961dbcbc…` = catalog **1**), which is the mirror image of the

package/knowledge/clients/quad/profile.md

@@ -142,4 +142,16 @@ Client-specific DB change-sets live in `dbchanges2/Client_Quad/`.
   Quad's **storefront only** (not orders/transmit), and Quad was the **only other client besides
   Compass** that needed a reversal. See
   [Quad catalog-fold reversal](./workflows/catalog-fold-reversal.md).
+- **Items listing being filtered to catalog 1 (written 2026-09-01, NOT yet applied) — verify the
+  intent for Quad first.** A migration sets `TableViews.apiWhereClause = '(Items.catalogId:eq:1)'`
+  on `Client_Quad`'s shared `items` view (`slug = 'items'`, id 9, recordId 21); the same one-line
+  change is going to `Client_Compass` and `Client_CompassCanada`. Read it against the bullet above:
+  for Quad, catalog 1 is the **storefront (Etilize)** catalog and catalog 2 is the **procurement
+  (Agilant/NetSuite)** catalog that Quad's storefront orders actually sit on, so `:eq:1` hides the
+  procurement half of `Client_Quad.Items` from the Supply items listing — a much bigger cut than the
+  equivalent change on Compass, and a majority of Quad's items. `Items.catalogId` is also nullable
+  here and a bare `:eq:1` drops those rows too; `IFNULL(Items.catalogId,1):eq:1` recovers the NULLs
+  but not catalog 2. Mechanism:
+  [TableView apiWhereClause row-filtering](../../2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md);
+  catalog background: [Compass item catalogs](../compass-usa/features/item-catalogs-and-duplicate-items.md).
 - This profile is a starting point; expand as more Quad-specific behavior is captured.

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.726",
+  "version": "1.0.728",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",