toga-ai 1.0.805 → 1.0.806

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

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-09-10
-owners: [snaredla, jcardinal, bala]
+updated: 2026-09-14
+owners: [snaredla, jcardinal, bala, apeterson]
 files:
   - _underscore/Model.php
   - _underscore/Model/Client/PurchaseOrder.php
@@ -218,6 +218,19 @@ characters — that is the standard of evidence for touching a field that runs o
 > even for a client whose subclass overrides it. `_Model_Compass_SalesOrder` has exactly this in its
 > ApprovalDecision notification query. Late static binding only happens with `static::`.
 
+## Filtering on a calculated field through the V2 API — it works, bare name only
+
+A calculated field **can** be used in a V2 `where`, and it is the cheapest way to cut a big list —
+but **only with the BARE name** (`_qtyAvailable`), never table-prefixed (`Table._qtyAvailable`,
+which is routed to a `HAVING` and returns 500 / `EO-1`). The full mechanism, the `ge`-not-`gte`
+and string-value traps, and the measured cost numbers live in
+[V2 REST query contract](../../api2/features/v2-rest-query-contract.md) — do not restate them here.
+
+Two consequences for whoever **writes** a calculated field: its SQL expression is inlined into a
+`WHERE`, so it must be a self-contained expression valid outside the `SELECT` list, and it is
+evaluated **per row** — the measured cost is roughly **1 s per named `_qty*` field per 1,238 rows**.
+Keep the expression cheap, or expect callers to pay for it on every list.
+
 ## Gotchas / known issues
 
 - **⚠ Never add a parameter TYPE to an override whose parent declares the parameter untyped - it
@@ -255,6 +268,10 @@ 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-14 — Added a **Filtering** section: a calculated field IS usable in a V2 `where` with the
+  bare (non-table-prefixed) name, which contradicts a belief written into several frontend repos.
+  Mechanism and cost figures cross-referenced to the api2 query contract rather than duplicated.
+  (apeterson)
 - 2026-09-10 — Added two NYCHH-only calc fields on `_Model_Nychh_Unit`
   (`_underscore/Model/Nychh/Unit.php`) for the rebuilt `units-for-items-for-purchase-orders` grid,
   both plain `FIELD_SQL` (text — no `FIELDOPT_SQL_TYPE`): **(a)** an **override** of

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-09-08
+updated: 2026-09-14
 owners: [tcox, bala, apeterson, jcardinal, rgirish]
 files:
   - api2/Component/Api/V2/V2.php
@@ -111,6 +111,29 @@ The same route's **list GET was ~1s**, so this is the **write read-back**, not t
   `api2`/`_underscore` is an **open follow-up** (needs a `cto` review before touching the shared
   serializer). Lowering caller depth is a mitigation, not the fix.
 
+### Measured cost of a list GET — it is per ROW × per NAMED CALCULATED FIELD × per FK hop
+
+One `GET /v2/purchase-order-items` over the **same 1,238 rows** (NYCHH, `sandbox-client`), one curl
+per line, 2026-09-14:
+
+| Request | Time |
+|---|---|
+| full field set as the app sent it, `calcDepth: 3` | **13.3 s** (785 KB) |
+| identical but `calcDepth: 1` | 13.3 s (byte-identical response) |
+| minus `_qtyOnHand` / `_qtyReceived` / `_qtyFulfilled` | 10.2 s |
+| minus `_qtyAvailable` as well | 6.1 s |
+| minus the `vendorItem → item` FK chain | 4.0 s |
+| `uuid`/`lineNumber`/`quantity` only — no FK, no calculated | 1.3 s |
+| full field set at `recordsPerPage: 100` | 1.7 s |
+| full field set **+ `where=(_qtyAvailable:ge:1)`** | **0.35 s** |
+
+Read: ~**11 ms per row** at the full field set. Three named `_qty*` calculated fields cost **3.1 s**
+across 1,238 rows; the `vendorItem → item` FK expansion another **~2 s**.
+
+**Therefore, in order of payoff:** (1) filter server-side so fewer rows are built at all — a
+`where` cut 13.3 s to 0.35 s, ~38×; (2) drop calculated fields nothing renders; (3) drop FK hops
+nothing renders; (4) page. Raising/lowering `calcDepth` changed nothing.
+
 ### ⚠ `calcDepth` defaults to **1** — a calculated field one FK hop out comes back NULL, silently
 
 `calcDepth` bounds how deep `FIELD_SQL` **calculated** fields are evaluated, independently of
@@ -127,6 +150,22 @@ calculated field is null on a nested object but correct when that object is fetc
 Definition of the fields themselves:
 [FIELD_SQL calculated fields](../../_underscore/features/calculated-sql-fields.md).
 
+#### ⚠ …but `calcDepth` does NOT gate a calculated field you NAME EXPLICITLY in `fields`
+
+The rule above holds for the **no-explicit-`fields`** path only. A calculated field written as a
+**dotted path inside `fields=`** — e.g. `vendorItem.item._thumbnailImageUrl`, two FK hops out — is
+classified as calculated at `V2.php` ~L3338, **before** the `calcDepth` gate is reached, so it
+resolves at the default `calcDepth: 1`.
+
+Verified 2026-09-14 on `GET /purchase-order-items` (1,238 NYCHH lines): the response is
+**byte-identical** at `calcDepth: 1` and `calcDepth: 3`, with the same 473 non-null thumbnails. So
+raising `calcDepth` "to cover the deepest hop" for a field you already named is **pure cost with no
+effect** — it does not make the request slower on its own, but it hides the real cost driver (the
+number of calculated fields, below).
+
+**Decide which path you are on first:** naming the field ⇒ ignore `calcDepth`; letting
+`getFullModelData()` serialize everything ⇒ the one-per-FK-hop rule applies.
+
 ### ⚠ A non-null FK object at the MAX requested `depth` is OMITTED from the response
 
 A GET serialized to `depth: N` renders FK objects down to level N, but a **non-null FK object that
@@ -276,6 +315,55 @@ where=(field:op:value,LOGIC,field:op:value,(nested,OR,nested))
 - **NULL has no operator.** Use the literal value `null`: `field:eq:null` → `IS NULL`,
   `field:ne:null` → `IS NOT NULL`.
 
+### ✅ You CAN `where` on a calculated (`FIELD_SQL`) field — but ONLY with the BARE name
+
+This corrects a widespread belief that a `where` on a calculated field is impossible. It works, and
+it is the single biggest performance lever on a large list (13.3 s → 0.35 s above). The **only**
+thing that has to be right is the shape of the field name:
+
+```
+where=(_qtyAvailable:ge:1)                      ✅ plain WHERE — HTTP 200, 0.35 s
+where=(PurchaseOrderItems._qtyAvailable:ge:1)   ❌ becomes a HAVING — HTTP 500 / EO-1
+```
+
+Mechanism, read from `api2/Component/Api/V2/V2.php`:
+
+1. `buildWhereExpressionsFromOptions` (~L6953) **deliberately does not prepend the default table**
+   to a field starting with `_` — its own comment says *"add the default table if not specified and
+   is not a calculated field."*
+2. `buildWhereClauseFromWhereExpressions` (~L7069) sees the leading `_` and **inlines the field's own
+   SQL expression** straight into the `WHERE` clause. That is the working path.
+3. `splitWhereExpressionsIntoWhereHaving` (~L8622) routes to `HAVING` **only when the field contains
+   `._`** — i.e. only the table-**prefixed** form. That form targets a joined-table select alias
+   (`PurchaseOrderItems__qtyAvailable`, built ~L3984) which **does not exist for the main table**,
+   and ~L4116 also appends the `HAVING` to the `$sqlProhibited` COUNT query, which has no such alias
+   either. Hence the 500.
+
+**The COUNT query is fine on the bare form.** `meta.totalRecordCount` comes back correct (`4`), and a
+filter that matches nothing returns a clean **200 with `totalRecordCount: 0`** — verified, it does
+**not** error on the empty case. So pagination is not broken by this, contrary to what several
+in-repo comments claim.
+
+Three things that fail **silently or misleadingly** and are worth locking with a test:
+
+- **The name must be bare** — `_qtyAvailable`, never `Table._qtyAvailable`.
+- **The operator is `ge`, not `gte`** — `gte` returns 500 / `EO-1` (same as every other op).
+- **The value must be a STRING** when you go through `@agilant/toga-blox` — `urlEncode` calls
+  `.replace()` on it, so a numeric value throws inside `buildUrl` and **no HTTP request is ever
+  sent** (see [blox api-client](../../toga-blox/features/api-client.md)).
+
+Corroboration that this is long-standing, not new: bare calculated fields in `where` already ship in
+production — `toga2-supply/src/api/toga.ts` L906-919 (`_status` OR group) and L886-893 (NYCHH
+`_total:ne:0`), `toga2-supply/src/pages/Orders/api/OrdersApi.ts:1900` (`_name`),
+`toga2-commerce/src/pages/Cart/api/CartApi.ts` L48/L257/L349 (`_name`),
+`toga25-supply/src/layout/RecordApprovalModal/view/ApprovalFlowDetailInputs.tsx:27` (`_name`).
+**Zero** occurrences of the table-prefixed form exist in any repo — nobody has ever used it
+successfully.
+
+> ⚠ **Scope this to `where` only.** It says nothing about `group` or `sort` on a calculated field;
+> `group=_status` is separately known to fail. And `where` still never prunes a nested child array
+> (see below).
+
 ## Encoding rules (the query string is never urldecoded at parse time)
 
 - Encode a literal `%` in a LIKE pattern as **`%25`**.
@@ -410,6 +498,11 @@ ACL gate for calculated fields lives at **:7216** in `getFullModelData()` — wh
 - **A 500 (`EO-1`) on a filter ⇒ suspect a `where` reference to an unjoined table.**
 - **A 500 (`EO-1`) reading `Invalid operator '' in WHERE conditions` ⇒ the `where` clause was URL-encoded.** The query string is never `urldecode`d — send it raw (see the encoding rules).
 - **`gte`/`lte` silently are not operators** — use `ge`/`le`.
+- **⚠ A 500 / `EO-1` on a `where` over a calculated field ⇒ you table-PREFIXED the field name.**
+  Drop the prefix: `_qtyAvailable`, not `PurchaseOrderItems._qtyAvailable`. The prefixed form is
+  routed to a `HAVING` against an alias that does not exist.
+- **⚠ Do not raise `calcDepth` for a calculated field you named in `fields=`** — it is classified
+  before the gate and already resolves at the default `1`.
 - **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. **⚠ Plain columns
   only** — an `_`-prefixed field named in `fields=` is never ACL-checked and returns `0`, not
@@ -428,6 +521,13 @@ ACL gate for calculated fields lives at **:7216** in `getFullModelData()` — wh
   [V2 request logging](request-logging.md).
 
 ## Change history
+- 2026-09-14 — **Corrected a wrong team-wide belief: a `where` on a calculated (`FIELD_SQL`) field
+  WORKS, with the BARE field name.** `_qtyAvailable:ge:1` is inlined into the `WHERE` and returns 200
+  with a correct `totalRecordCount`; only the table-prefixed `Table._qtyAvailable` form is routed to a
+  `HAVING` against a non-existent alias and 500s. Also recorded that **`calcDepth` does not gate a
+  calculated field named explicitly in `fields=`** (byte-identical response at `calcDepth` 1 vs 3),
+  and added a **measured per-row cost model** for a list GET (13.3 s → 0.35 s by filtering
+  server-side). Found while fixing the toga25-supply Create Transfer Order item picker. (apeterson)
 - 2026-09-04 — Recorded the **URL-encoded `where` trap** hit while debugging a production Rate/AIG
   incident: `parseOptionsWhere` (`V2.php` ~L325) reads `$_SERVER['QUERY_STRING']` with no
   `urldecode()`, so an encoded clause (curl `--data-urlencode`, `requests` `params=`,

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-10
+updated: 2026-09-14
 owners: [apeterson, bala]
 files:
   - toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateTransferOrder.ts
@@ -30,6 +30,7 @@ files:
   - 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/usePurchaseOrderItemRows.test.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
@@ -457,10 +458,14 @@ New hooks/components: `hooks/usePurchaseOrderItemRows.ts`, `hooks/useTargetLocat
    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
+### 🚨 OPEN BLOCKER — NYCHH availability is structurally 0, and it is not a frontend fix
 
-The picker keeps only lines with availability >= 1. For NYCHH there are **none**, in sandbox **and**
-production.
+The picker keeps only lines with availability >= 1.
+
+> **State as of 2026-09-14 (`sandbox-client`): 4 of 1,238 lines now qualify** — availability equal to
+> the full ordered quantity on each. It is no longer literally zero there, so a tester does get rows.
+> **Production not re-checked.** The blocker itself is unchanged: 1,234 of 1,238 still report 0.
+> Uuids and figures: [NYCHH transfer-order inventory quantities](../../../../clients/nychh/features/transfer-order-inventory-quantities.md).
 
 `_Model_Nychh_PurchaseOrderItem` (deployed on `_production` and `_sandbox-client`, absent on
 `_beta`/`_sandbox-dev`) sources "stock in" from inventory adjustments and `INNER JOIN`s
@@ -547,6 +552,82 @@ push) — see
 `contact: { uuid }`, `createdByUser: { uuid }`. Each is omitted entirely when absent rather than sent
 as `null`: a location can have no contact, and an SSO session can lack a user uuid.
 
+### The picker fetch — 13.3 s → 0.39 s by filtering SERVER-side (2026-09-14)
+
+`hooks/usePurchaseOrderItemRows.ts` used to fetch **every** NYCHH purchase-order line and then drop
+the unavailable ones with a client-side `.filter(r => r.available >= 1)`. That cost **13.3 s** to
+open the modal and built 1,238 rows to keep 4.
+
+The availability filter now goes in the request:
+
+```ts
+where: { and: [{ _qtyAvailable: { ">=": "1" } }] }
+// blox serializes this to  where=(_qtyAvailable:ge:1)
+```
+
+Measured end to end: **0.39 s**, same 4 rows, every row with its linked item uuid, PO number and
+thumbnail key. Four changes made it, in order of payoff:
+
+1. **The `where` above** — 13.3 s → 0.35 s on the wire. This is the whole win.
+2. **Dropped `calcDepth: 3`.** It was sent to "reach" `vendorItem.item._thumbnailImageUrl`, two FK
+   hops out. `calcDepth` does **not** gate a calculated field you name explicitly in `fields` — the
+   response is byte-identical at 1 and 3.
+3. **Dropped `_qtyOnHand` / `_qtyReceived` / `_qtyFulfilled` from the main fetch** — 3.1 s, and
+   nothing renders them; they only fed a diagnostic string (see the probe below).
+4. **Removed the `onHand` field from `PurchaseOrderItemRow`** and the `noAvailabilityCount`
+   diagnostic, both unrendered.
+
+Three traps, all of which fail **silently**, so the wire form is now locked by a regression test
+(`hooks/usePurchaseOrderItemRows.test.ts`, 6 tests) and the request options are built by a pure
+exported `buildRowRequestOptions(ignoreAvailability)` so they are testable:
+
+- **The field name must be BARE.** `PurchaseOrderItems._qtyAvailable` becomes a `HAVING` and 500s.
+- **The operator is `ge`, not `gte`.**
+- **The value must be the STRING `"1"`.** A number throws inside blox `buildUrl` and no request is
+  sent at all.
+
+Full mechanism and the measured cost table:
+[V2 REST query contract](../../api2/features/v2-rest-query-contract.md).
+
+> 🧹 **Stale comments to correct when you are next in these files.** The opposite belief — *"a WHERE
+> on a calculated field becomes a HAVING, and a HAVING breaks V2's count query and therefore
+> pagination"* — is written into six places and is why nobody tried it. Corrected in
+> `usePurchaseOrderItemRows.ts` this session; **still wrong** in `src/hooks/useEntitySearch.ts:15-19`,
+> `src/layout/ItemRecordModalLayout/viewModel/useItemRecordEditViewModel.tsx:44-45`,
+> `src/layout/VendorItemRecordModalLayout/viewModel/useVendorItemRecordEditViewModel.tsx:69-70`,
+> `src/layout/BundleRecordModalLayout/viewModel/useBundleRecordCreateViewModel.tsx:9-10`,
+> `src/layout/BundleRecordModalLayout/viewModel/useBundleRecordEditViewModel.tsx:10`,
+> `src/layout/BundleItemRecordModalLayout/viewModel/useBundleItemSelectsViewModel.tsx:9`.
+
+#### ⚠ Moving a filter server-side DESTROYS your empty-state evidence — pair it with a lazy probe
+
+This is the reusable part, not a detail of this screen. Once the filter is on the server, **"no rows"
+means two completely different things at once**: *nothing is in stock*, or *the field never came back
+at all* — an ungranted or misnamed calculated field is dropped from the SELECT silently and reads as
+a real `0`. The old code could tell them apart only because it fetched everything.
+
+The pattern adopted here: a **second `useQuery`, `enabled` only when the main query succeeds with
+zero rows**, fetching an **unfiltered sample** — 5 rows, `depth: 1`, the full
+`_qtyReceived`/`_qtyFulfilled`/`_qtyOnHand`/`_qtyAvailable` chain. It costs **0.27 s and only on the
+failure path**; the happy path pays nothing. It restores the `sampleBreakdown` string and the
+"field absent vs. real zero" count, and its `meta.totalRecordCount` gives the tenant's true line
+count (1,238) — which the filtered main request no longer reports.
+
+`CreateTransferOrderModal.tsx` gained a `diagnostics.isPending` branch so the empty state reads
+**"Checking purchase-order lines…"** rather than accusing the API of returning 0 lines while the
+probe is still in flight.
+
+#### ⚠ A dev flag that overrides a value CLIENT-side must also drop the SERVER-side filter on it
+
+`VITE_TRANSFER_IGNORE_AVAILABILITY=true` substitutes the PO line's ordered `quantity` for
+`_qtyAvailable` **client-side**. With the filter moved to the server, the API would return only the
+already-available lines and there would be nothing left to substitute — the escape hatch would have
+died silently. The flag therefore now **also omits the `where` clause entirely**.
+
+That is the general rule, and it is why the client-side `available >= 1` filter was **kept**: it is a
+no-op on the normal path, and it is what actually filters under the escape hatch, which sends no
+`where`.
+
 ### The picker is VIRTUALIZED — spacer rows inside a real `<table>` (2026-09-03)
 
 `view/TransferItemPickerTable.tsx` renders through **`@tanstack/react-virtual`**. The rendering
@@ -563,6 +644,50 @@ Measured on a 1,232-row list: median keystroke latency **248 ms → 24 ms**, DOM
 > whatever the user is actually typing in. Replaced with an explicit `ref` + `useEffect` that focuses
 > **once**, on the row that was just checked.
 
+### Skeleton loading in the picker — real rows under the table's own `<colgroup>` (2026-09-14)
+
+`view/TransferItemPickerTable.tsx` replaced the single "Loading items…" text cell with **8 placeholder
+rows**. They are real `.row` / `.td` elements rendered **under the table's own `<colgroup>`**, so
+column widths, row height and dividers match the loaded table exactly and **nothing shifts sideways**
+when data arrives — which a single spanning text cell cannot do.
+
+- Reuses the module's existing `.skBlock` / `toTransferPulse` treatment (the one the Transfer Order
+  **record** modal already uses) rather than introducing a second skeleton style.
+- Rows are `aria-hidden`, with `aria-busy` on the scroll region; the existing
+  `prefers-reduced-motion` block now covers them too.
+
+Two gotchas:
+
+- **`.skRow .skBlock` is `display: block`, so `.selCell`'s `text-align: center` does NOT centre the
+  checkbox placeholder** — it needs `margin: 0 auto`. The real control is an inline `<input>`, which
+  is why the loaded row looks right and only the skeleton looked wrong. Same reason
+  `.alignRight .skBlock` needs `margin-left: auto`.
+- **Keep the skeleton branch separate from the virtualizer branch**, or the two spacer `<tr>`s render
+  while loading.
+
+> ⚠ **Not in the Claude Design source** — `demo/transfer-modal.jsx` has no loading state. This follows
+> the in-repo record-modal treatment instead, and was flagged to the developer as a deviation.
+
+### Testing the picker hook — mock the blox barrel or the suite dies on `global.css`
+
+A test importing a module that imports `apiGet` from the `@agilant/toga-blox` barrel fails with:
+
+```
+TypeError: Unknown file extension ".css" for node_modules/@agilant/toga-blox/dist/global.css
+```
+
+House fix, matching `src/components/TableStateBlock/TableStateBlock.test.tsx`:
+
+```ts
+vi.mock("@agilant/toga-blox", () => ({ apiGet: () => undefined }));
+```
+
+The 6 picker tests were **seen to fail before passing**: reintroducing the table-prefixed field name
+turned 3 red, making the value numeric turned 2 red, green again after restore.
+
+> `src/hooks/useTalosSurface.test.ts` fails with the **same** `global.css` error and is
+> **pre-existing** — it fails identically with this work stashed. Do not chase it as a regression.
+
 ### A new transfer POSTs an initial stage — and the stage is sent as `{ id }`, NOT `{ uuid }`
 
 `hooks/useCreateTransferOrder.ts` now sends an opening stage. **`TransferOrderStages` has no `uuid`
@@ -922,6 +1047,11 @@ deliberate, separate exception — see [surface-frontend](./surface-frontend.md)
   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.
+- **⚠ A `where` on a calculated field works — but BARE only.** `_qtyAvailable:ge:1` is fine;
+  `PurchaseOrderItems._qtyAvailable:ge:1` becomes a `HAVING` and returns 500 / `EO-1`. Several
+  in-repo comments still claim the whole thing is impossible; they are wrong (list above).
+- **⚠ An empty list is ambiguous once the filter is server-side** — it could be "nothing in stock"
+  or "the field never came back". Run the unfiltered diagnostic probe before blaming either.
 - **⚠ An ungranted `uuid` field 403s the WHOLE request** — `uuid` is V2's `IDENTIFIER_FIELD` and is
   force-added to every record read, so a record whose role lacks an `AclFieldPermissions` grant on
   its `uuid` RecordField returns **403 `EZ-2`** listing `"fields": ["uuid"]`. Ordinary ungranted
@@ -993,6 +1123,17 @@ 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-14 — **Create Transfer Order item picker: 13.3 s → 0.39 s.** Moved the availability filter
+  into the request as `where=(_qtyAvailable:ge:1)` (bare calculated-field name — the table-prefixed
+  form 500s), dropped the pointless `calcDepth: 3` and three unrendered `_qty*` fields, and locked the
+  wire form with 6 regression tests. Added a **lazy unfiltered diagnostic probe** that runs only when
+  the main query returns zero rows, because a server-side filter otherwise makes "nothing in stock"
+  and "the field never came back" indistinguishable. `VITE_TRANSFER_IGNORE_AVAILABILITY` now also
+  omits the `where`, or the escape hatch would have silently died. Added **skeleton loading rows** to
+  the picker (real rows under the table's `<colgroup>`, reusing the record modal's `.skBlock`
+  treatment). Also noted that the NYCHH blocker has partially cleared on `sandbox-client` — 4 of
+  1,238 lines now selectable, blocker still open. Nothing committed; work sits on `TRUE-80852`.
+  (apeterson)
 - 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

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-09-02
+updated: 2026-09-14
 owners: [jcardinal, apeterson]
 files:
   - _underscore/Model/Nychh/Item.php
@@ -279,6 +279,30 @@ is exactly the shape of option **(b)** above. Left **UNRESOLVED and handed to Je
 same integration/data-owner decision, and the evidence above narrows it to the override's stock-in
 source rather than anything in the request path.
 
+#### 2026-09-14 — PARTIALLY cleared on sandbox: 4 lines now report availability (blocker still OPEN)
+
+Re-measured on `sandbox-client`: of **1,238** NYCHH purchase-order lines, **4** now report
+`_qtyAvailable >= 1`. The other **1,234 still report 0.**
+
+| `PurchaseOrderItems.uuid` | `quantity` | `_qtyAvailable` |
+|---|---|---|
+| `31c5871e-97da-7838-b3aa-ac8b9a21cf01` | 29 | 29 |
+| `38e83217-759d-bf7d-8c27-940501603473` | 7 | 7 |
+| `67039882-8aed-d68d-dcd5-cbf089b4ab6b` | 4 | 4 |
+| `f574526e-3de1-f182-e8ba-3945ecd36765` | 100 | 100 |
+
+On all four, availability equals the **full ordered quantity** — i.e. these are newly linked lines
+with nothing dispatched yet, not partial recoveries. **Not verified on production.**
+
+What this changes and what it does not:
+
+- **Changed:** "the picker shows nothing for NYCHH" is now stale for `sandbox-client` — it shows 4.
+  Anyone testing the Create Transfer Order flow there now has real selectable rows.
+- **NOT changed:** the underlying blocker stands. The unbackfilled
+  `InventoryAdjustmentItems.itemFulfillmentItemId` link is still NULL on ~all rows, and options
+  **(a)** and **(b)** above still need the integration / data-owner decision. Do not close this on
+  the strength of 4 rows.
+
 ### The role-3 grant migration is NOT the fix for the empty picker
 
 `dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql` grants **role 3 (API)**
@@ -413,6 +437,10 @@ pattern (default a NOT NULL non-writable column in the model, never send it) is
   session — and a *passing* drift check on the base `Model/Client/` file is what made it feel safe.
 
 ## Change history
+- 2026-09-14 — **Blocker partially cleared, not resolved.** On `sandbox-client`, 4 of 1,238 NYCHH
+  PO lines now report `_qtyAvailable >= 1` (each equal to the full ordered quantity); 1,234 still
+  report 0. Production not re-checked. The `itemFulfillmentItemId` backfill decision is still open —
+  the state line changed, the blocker did not. (apeterson)
 - 2026-09-02 — **Re-hit the `_qty*` = 0 blocker on a second line and narrowed it two steps further.**
   Reference row `PurchaseOrderItems` uuid `715ef031-003d-6742-871d-0d20de2fa40f` (PO 80622, line 21):
   the V2 API returns `quantity: 3270` **correctly** while `_qtyReceived`/`_qtyOnHand`/`_qtyAvailable`/

package/package.json

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