toga-ai 1.0.804 → 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/toga-blox/features/primary-table-templates.md

@@ -6,7 +6,7 @@ project: TOGa Blox
 client: shared
 type: feature
 status: active
-updated: 2026-08-31
+updated: 2026-09-14
 owners: [apeterson, tcox]
 files:
   - toga-blox/src/components/Table/themeConfig/toga.module.css
@@ -22,6 +22,7 @@ files:
 related:
   - ../architecture.md
   - table.md
+  - ../../toga25-supply/features/server-table-url-state.md
 ---
 
 ## Summary
@@ -132,6 +133,15 @@ runs unconditionally — it no longer no-ops while `isExpanded`.
 
 ## Gotchas
 
+- **`PrimaryTableServerTemplate` is FULLY controlled — its change handlers fire only on real user
+  interaction.** `state: { sorting, columnFilters }` is passed in and `manualSorting`,
+  `manualFiltering`, and `manualPagination` are all `true`, so `onSortingChange` /
+  `onColumnFiltersChange` **never fire on mount**. That is what makes it safe for the consumer to
+  mutate other URL state (e.g. reset `page` to 1) inside those handlers: no handler runs without
+  user intent, so a shared deep link like `?…_page=3` can never be clobbered on load. blox only
+  *reads* the view state; the app owns the URL. See
+  [toga25-supply server table URL state](../../toga25-supply/features/server-table-url-state.md).
+
 - **Never gate a hover affordance on a JS `mouseleave` inside a virtualized table.** `mouseleave`
   is not guaranteed to fire: a virtualized row can translate out from under a stationary cursor on
   wheel-scroll, and any early-return in the clear handler strands the "hovered" flag set. The toggle
@@ -164,6 +174,9 @@ runs unconditionally — it no longer no-ops while `isExpanded`.
   not the column set.
 
 ## Change history
+- 2026-09-14 — Recorded that the server template is fully controlled (`manual*` + passed-in
+  `state`), so its sort/filter handlers never fire on mount — the property a consumer relies on
+  when resetting pagination from inside those handlers. No code change. (apeterson)
 - 2026-08-31 — Host-tokenized the `supply`-skin table shadow: `.tableAndPaginationInner.supply` /
   `.tableWrapper.supply` now use `box-shadow: var(--primaryTable-box-shadow, 0 1px 3px rgba(0,0,0,0.1))`,
   adding `--primaryTable-box-shadow` to the host-token set (a design review needed the shadow gone and

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

@@ -11,6 +11,7 @@
 | [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s |
 | [Persisted React Query cache (localStorage `supply-chain-query-cache`)](features/persisted-query-cache.md) | `localStorage["supply-chain-query-cache"]` is **not a hand-written cache**. |
 | [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. |
+| [Server Table URL State (page, sort, filters) — `useServerTableUrlState`](features/server-table-url-state.md) | `src/hooks/useServerTableUrlState.ts` is the app's single source of truth for a server-paged table's **view state**: page, records-per-page, sorting, column fil |
 | [Side navigation & default route — an empty nav renders a BLANK PAGE and gets reported as "cannot log in"](features/side-navigation-and-default-route.md) | The 2.5 side nav is **100% backend-driven** by the `navigation` surface bundle, and the same list also decides **which routes exist** and **where `/` lands**. |
 | [SSO redirect & public-vs-user session gating (useAuthenticationFlow)](features/sso-redirect-and-session-gating.md) | How 2.5 Supply decides, on every navigation, whether an anonymous visitor should be bounced to their client's SSO IdP instead of the local `/login` form. |
 | [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J |

package/knowledge/2.0/apps/toga25-supply/features/column-visibility.md

@@ -23,6 +23,7 @@ related:
   - ../architecture.md
   - client-configurable-fields.md
   - meta-driven-table-data.md
+  - server-table-url-state.md
   - surface-frontend.md
   - transfer-orders-page.md
   - ../../dbchanges2/features/surface-layer-schema.md

package/knowledge/2.0/apps/toga25-supply/features/meta-driven-table-data.md

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
+updated: 2026-09-14
 owners: [apeterson]
 files:
   - toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx
@@ -22,6 +22,7 @@ related:
   - column-visibility.md
   - record-modals-and-nested-tables.md
   - transfer-orders-page.md
+  - server-table-url-state.md
   - ../../_underscore/features/page-meta-context-field-settings.md
 ---
 
@@ -162,7 +163,10 @@ App-side glue (NOT in toga-blox):
 - `useTablePageMeta` (`src/hooks/useTablePageMeta.ts`) — thin wrapper over `useFetchTablePageMeta`
   that re-types `table`/`nestedTable` as `TableViewMeta | null` and re-exposes the rest unchanged.
 - `useSalesOrdersTableState` → `useServerTableUrlState` (`src/hooks/`) — derives the **table slug**
-  from the route pathname and owns URL-backed sorting/filters/pagination/active-row state.
+  from the route pathname and owns URL-backed sorting/filters/pagination/active-row state. It is the
+  app's only writer of `<slug>_page`, and it resets the page to 1 on any filter/sort/page-size
+  change — the full param grammar and that rule live in
+  [server-table-url-state](./server-table-url-state.md).
 
 ## Wiring a new page (recipe)
 
@@ -198,6 +202,8 @@ App-side glue (NOT in toga-blox):
   raw camelCase slugs. Plan the label source before building the screen (see above).
 
 ## Change history
+- 2026-09-14 — Pointed the table-state bullet at the new `server-table-url-state` doc, which now
+  owns the `<slug>_*` param grammar and the reset-to-page-1 rule. No code change. (apeterson)
 - 2026-08-28 — Recorded that `_Model_Client_TableView::meta()` emits **no `label`** for a column, so
   every header comes from the page meta and `useAssignTableFieldLabels` **bails on a null `pageMeta`**
   (`if (!pageFields) return table`): a new list screen without a legacy `<slug>-listing` page-meta

package/knowledge/2.0/apps/toga25-supply/features/server-table-url-state.md

@@ -0,0 +1,147 @@
+---
+title: Server Table URL State (page, sort, filters) — `useServerTableUrlState`
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-09-14
+owners: [apeterson]
+files:
+  - toga25-supply/src/hooks/useServerTableUrlState.ts
+  - toga25-supply/src/hooks/useServerTableUrlState.test.ts
+  - toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts
+related:
+  - ../architecture.md
+  - meta-driven-table-data.md
+  - column-visibility.md
+  - record-modals-and-nested-tables.md
+  - ../../toga-blox/features/primary-table-templates.md
+  - ../../../standards/frontend.md
+---
+
+## What it is
+
+`src/hooks/useServerTableUrlState.ts` is the app's single source of truth for a server-paged
+table's **view state**: page, records-per-page, sorting, column filters, filter/sort ordering,
+and the active (clicked) row. It reads that state out of the query string and gives the page
+back handlers that write it. Every list page goes through it — Sales Orders via
+`useSalesOrdersTableState`, and the same shape for the other pages.
+
+All params are **namespaced by the table slug**, so two tables on one URL never collide.
+
+> It is the **only writer of `<slug>_page` in the whole app** (verified by grep across `src/`,
+> 2026-09-14). There is no second pagination code path to keep in sync. `useEntitySearch` is for
+> `advancedSelect` dropdown pickers and holds no pagination URL state; the only "search" on a
+> main table view is blox's per-column `HeaderFilterSearch`, which routes into
+> `handleColumnFiltersChange` here.
+
+## The param grammar
+
+| Param | Meaning |
+|---|---|
+| `<slug>_page` | current page (default `1`) |
+| `<slug>_recordsPerPage` | page size (default `15`) |
+| `<slug>_sort[i]` | sort at position `i`, value prefixed `+` asc / `-` desc |
+| `<slug>_<field>` | bare form = `includes` (substring match) |
+| `<slug>_<field>_starts` / `_ends` / `_eq` / `_excludes` | `startsWith` / `endsWith` / `exactly` / `excludes` |
+| `<slug>_<field>_in` | multi-select over a closed option set — **exact** values, one SQL `IN` |
+| `<slug>_<field>_between` / `_before` / `_after` / `_min` / `_max` | range params, collected into one `{ params }` filter value |
+| `<slug>_<field>_filter` | multi-chip text filter: comma-separated `mode:value` chips, values URL-encoded, all AND'd |
+| `<slug>_<field>_order` | the filter's display order (default `999`) |
+| `<slug>_actionOrder` | shared order of applied filter/sort chips |
+| `<slug>` (bare) | `activeRowUuid` — the open record modal |
+
+The reader loops `searchParams`, matches by suffix, and falls through to `includes` for the bare
+form — which is why the fall-through explicitly **excludes** `_order`, `_sort`, `_page`,
+`_recordsPerPage`, and `_actionOrder` so a control param is never mistaken for a filter. Add a new
+control param and you must add it to that exclusion list.
+
+### `_in` is exact, not `includes`
+
+`_in` used to alias the bare `includes` form, so picking `fulfilled` in a multi-select also matched
+`partiallyFulfilled`. It is now its own `mode = "in"` on the read side with a matching
+`case "in":` on the write side: exact values, serialized downstream as one SQL `IN`.
+
+## How it works — any result-changing param resets to page 1
+
+🚨 **This is the load-bearing rule of the hook.** A change to *which records the server returns* —
+a filter/search, a sort, or a page size — must send the user back to page 1.
+
+One helper, one home:
+
+```ts
+const FIRST_PAGE = "1";
+
+const resetToFirstPage = useCallback(
+    (prev: URLSearchParams) => { prev.set(`${slug}_page`, FIRST_PAGE); },
+    [slug],
+);
+```
+
+Called by all three result-changing handlers — `handleColumnFiltersChange`,
+`handleSortingChange`, `handleRecordsPerPageChange`.
+
+Two details that matter:
+
+1. **The reset is written inside the SAME `setSearchParams(prev => …)` updater** as the
+   filter/sort write. One history entry, one React Query refetch — so the back button undoes the
+   filter and the page together instead of leaving a half state.
+2. **`handleRowClick` deliberately does NOT reset.** Opening a record modal must not throw the
+   user back to page 1. Neither does `handlePageChange`, obviously.
+
+This is the concrete implementation of the rule in
+[`standards/frontend.md` §5](../../../standards/frontend.md) — a param that changes the query
+result belongs in the React Query key *and* resets to page 1.
+
+### Why an app-side reset is safe (it does not clobber deep links)
+
+blox's `PrimaryTableServerTemplate` builds the table **fully controlled**: `state: { sorting,
+columnFilters }` with `manualSorting` / `manualFiltering` / `manualPagination: true`. So
+`onColumnFiltersChange` / `onSortingChange` fire **only on real user interaction, never on mount**.
+Nothing runs a reset on load, which is what lets a shared `?…_page=3` URL survive. The app owns the
+URL state; blox only reads it. The fix therefore needed **no blox change, no publish, no pin bump**
+— confirmed by the install being a real registry copy (no symlink), pinned exactly.
+
+## Gotchas
+
+- **A "backend search returns nothing" report is usually this bug.** Symptom: user on page 2
+  searches for a PO number that lives on page 1 and gets an empty table. The front end sent the
+  new filter with `<slug>_page=2` still set, api2 paged the *new* (filtered) result set from page
+  2, and the single match — now on page 1 — fell outside the slice. It reads exactly like an api2
+  search defect and is not one. Check the query string before you open the API.
+- **Page size worked while search did not.** `handleRecordsPerPageChange` already reset the page;
+  the filter and sort handlers never did. If only *some* controls behave, suspect an incomplete
+  reset rather than a data-layer problem.
+- **Clearing all filters also resets to page 1** — by decision, see below. Do not re-add an
+  `if (next.length > 0)` guard around the reset.
+- **The hook's filter read/write block is a merge hot spot but not a conflict magnet.** Two
+  independent fixes landed in it within days (the page reset, and the `_in` exact-match change a
+  few lines away) and `git merge` resolved them clean with both surviving. Verify both markers by
+  grep after such a merge rather than assuming a loss.
+
+## Tests
+
+Co-located `src/hooks/useServerTableUrlState.test.ts` (Vitest). The reset rule is covered by 8
+cases, every one **seen to fail before the fix** (5 red on the original code): filter applied,
+multi-chip text filter applied, filters cleared, one of two filters removed, sort applied, sort
+cleared, records-per-page changed, and the negative control — **row click must NOT reset**.
+
+Type-check with `npx tsc --noEmit -p tsconfig.app.json`. Bare `npx tsc --noEmit` is a silent no-op
+in this repo (references-only root config — see `standards/frontend.md` §2).
+
+## Decisions
+
+- **2026-09-14 — clearing filters DOES reset to page 1. The opposite was tried and reversed.**
+  Mid-session the reverse was implemented (keep the page on a filter clear, on the reasoning that
+  clearing only widens the result set so page 3 still exists), verified with a mutation test, then
+  deliberately undone. Final behavior: **every** filter change resets, including a full clear.
+  Recorded so nobody re-litigates it or re-adds the guard thinking it was an oversight.
+
+## Change history
+- 2026-09-14 — Documented the hook as its own subject. Added `resetToFirstPage` so filters, sorts,
+  and page-size changes all return to page 1 (fixes "search on page 2 finds nothing", TRUE-81877);
+  recorded the reversed keep-the-page-on-clear decision; noted `_in` is now exact-match not
+  `includes`; deleted ~104 lines of commented-out dead `activeRowUuid`/handler variants from the
+  bottom of the file (503 → 399 lines). (apeterson)

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/2.0/apps/toga25-supply/workflows/cypress-testing.md

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: workflow
 status: active
-updated: 2026-09-03
+updated: 2026-09-14
 owners: [apeterson]
 files:
   - toga25-supply/cypress.config.ts
@@ -253,10 +253,11 @@ Every `cy:*` script goes through **`node scripts/cypress.mjs`** — see the firs
 
 - **Vitest is the other half.** `npm test` (`vitest run`) currently has **one failing test file**:
   `src/hooks/useTalosSurface.test.ts` fails with
-  `TypeError: Unknown file extension ".css"` on `@agilant/toga-blox/dist/global.css`. 89 tests pass
-  across the other 13 files. **Pre-existing** — the file was last touched in commit `604a779` and
-  the Cypress work changed neither it nor `vitest.config.ts`. Needs a separate fix (Vitest CSS
-  handling for blox imports).
+  `TypeError: Unknown file extension ".css"` on `@agilant/toga-blox/dist/global.css` — the suite
+  fails to **load**, so it is silently skipped in full. **Pre-existing** — the file was last
+  touched in commit `604a779` and the Cypress work changed neither it nor `vitest.config.ts`.
+  Re-confirmed on a clean tree 2026-09-14, with every other file green (148/148 on
+  `_sandbox-client`). Needs a separate fix (Vitest CSS handling for blox imports).
 - **No other mechanical guardrails exist in this repo:** no `.github/workflows`, no husky, no
   lint-staged. The only `.git/hooks/pre-commit` is a machine-local `code-review-graph` shim that
   always exits 0 and is not checked in.
@@ -264,6 +265,9 @@ Every `cy:*` script goes through **`node scripts/cypress.mjs`** — see the firs
   `SurfaceOverrides IS_VISIBLE` row in `dbchanges2`; the fixture only simulates the grant.
 
 ## Change history
+- 2026-09-14 — Re-confirmed the `useTalosSurface.test.ts` / blox `dist/global.css` Vitest load
+  failure on a clean tree and refreshed the pass counts (148/148 on the rest). Still unfixed; it
+  silently costs one whole suite. No code change. (apeterson)
 - 2026-09-03 — **Rebuilt the harness from scratch on `TRUE-81735`** (the `TRUE-79813` harness this
   doc used to describe was never merged and is stranded there). New shape: all `/v2` calls stubbed,
   four tenants (COMPASS/COMPASSCANADA/NYCHH/QUAD), the three-axes model (client = baseUrl, role =

package/knowledge/2.0/standards/frontend.md

@@ -5,12 +5,13 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-09-03
+updated: 2026-09-14
 owners: [jcardinal, apeterson]
 files: []
 related:
   - ../apps/toga25-supply/architecture.md
   - ../apps/toga-blox/architecture.md
+  - ../apps/toga25-supply/features/server-table-url-state.md
   - frontend-deploy.md
   - backend-php.md
 ---
@@ -220,7 +221,18 @@ you are in.
   explicitly cleared" are different states. Use `searchParams.has(key)`, not a truthiness check on
   the value.
 - **A param that changes the query result MUST be part of the React Query key.** Page, sort, and
-  filters belong in the key so a change refetches (and resets to page 1).
+  filters belong in the key so a change refetches.
+- **A param that changes WHICH RECORDS the server returns MUST also reset the page to 1** — in the
+  **same** `setSearchParams(prev => …)` updater as the change itself, so the two land in one
+  history entry and one refetch. This covers filters/search, sort, and page size. It does **not**
+  cover opening a record (a row click must not throw the user back to page 1) or a presentation-only
+  param. Miss it and the app sends the new filter with the old page: the server pages the *new*
+  result set from page 2, the single match now on page 1 falls outside the slice, and the report
+  arrives as "the backend search returns nothing." Verified 2026-09-14 in `toga25-supply` — the
+  rule above was read as query-key-only, so `handleRecordsPerPageChange` reset the page while
+  `handleColumnFiltersChange` and `handleSortingChange` never did. Keep the reset in **one** helper
+  called by every result-changing handler, not inlined per handler. (See
+  `../apps/toga25-supply/features/server-table-url-state.md`.)
 - **A presentation-only param MUST be excluded from the key.** Column visibility changes what you
   see, not what the server returns — putting it in the key forces a pointless refetch. (See
   `../apps/toga25-supply/features/column-visibility.md`.)
@@ -785,6 +797,10 @@ Copy from there rather than reinventing.
 
 ## Change history
 
+- 2026-09-14 — Split §5's query-key bullet: reset-to-page-1 is now its own MUST (same
+  `setSearchParams` updater, one helper, row click excluded). It was previously a parenthetical
+  inside the query-key rule and went unimplemented for filters and sorts in toga25-supply for
+  months. (apeterson)
 - 2026-09-03 — §23 correction: replaced the two "seen to fail" worked examples. The first pass
   listed a guardrail check plus an **unverified** component-config mutation; both are now the two
   mutations that were actually run and observed red (a registry/fixture nav mismatch, and forcing

package/knowledge/INDEX.md

@@ -31,7 +31,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 13 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 21 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
-- **toga25-supply** (TOGa 2.5 Supply) — 20 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
+- **toga25-supply** (TOGa 2.5 Supply) — 21 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 14 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 - **bdr** (BDR) — 0 doc(s) → [2.0/apps/bdr/INDEX.md](2.0/apps/bdr/INDEX.md)
 

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.804",
+  "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",