toga-ai 1.0.805 → 1.0.807

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/_underscore/features/model-interceptor-unit-testing.md

@@ -6,12 +6,13 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-10
+updated: 2026-09-11
 owners: ["bala"]
 files:
   - _underscore/Test/bootstrap.php
   - _underscore/Test/Prudential/ServiceRequestTest.php
   - test/@Bala/tests/netsuite_salesorder_payload_tests.php
+  - _underscore/Test/Compass/
 related:
   - ../../../../clients/prudential/features/service-request-address-validation.md
   - ../../worker2/features/netsuite-salesorder-outbound-push.md
@@ -44,6 +45,7 @@ Prudential `validateCustomer()` guard (see the service-request address-validatio
 4. Run it with:
 
    ```
+   # there is no phpunit binary in the repo - see the section below
    phpunit --bootstrap _underscore/Test/bootstrap.php _underscore/Test
    ```
 
@@ -51,6 +53,29 @@ The initial suite covers the `validateCustomer()` guard: absent `customer`, null
 empty-string `uuid`, whitespace-only `uuid`, error-message content, and a valid `uuid` passing.
 Verified 6/6 passing against the real code.
 
+### There is no PHPUnit - newer suites are standalone runnable scripts
+
+`_underscore` still has **no `composer.json` and no `phpunit` binary**, so the `phpunit --bootstrap`
+line above only works if a developer has PHPUnit installed globally. The pattern that actually
+travels is a **plain runnable script**: `php Test/Compass/<file>.php`, **exit 0 on pass**. The
+Compass step-1 approval guard (`_underscore/Test/Compass/`, branch `TRUE-81900`) added three shapes
+worth reusing:
+
+1. **Stubbed** - fakes `_Query` and drives the real guard down every branch. No database.
+2. **Real-database** - points `_Query` at a **local MySQL copy** so the generated SQL actually
+   executes against the real schema. It finds its own fixtures **by query** and reports **SKIP**
+   (not FAIL) when a particular copy lacks them, so it never fails for the wrong reason.
+3. **Replay sweep** - replays real historic approvals and compares **every** verdict against plain
+   SQL (6,000 approvals for that guard).
+
+The stubbed suite proves the logic, the real-database suite proves the **SQL** is valid against the
+live schema, and the sweep proves the verdict matches production reality. They are complementary -
+picking only one leaves a whole class of bug uncovered.
+
+**Prove the suite catches regressions with mutation testing.** There is no coverage tool here, so
+three deliberate breaks were introduced and each had to be caught before the suite was trusted. Do
+this for any hand-rolled suite.
+
 ## Gotchas / known issues
 
 - **Reflection on private methods is the pattern here** — the interceptor validators are private,
@@ -69,7 +94,25 @@ Verified 6/6 passing against the real code.
   `--bootstrap` file to wire up requires. Adding more model tests means extending
   `Test/bootstrap.php` with the stubs that model needs.
 
+- **⚠ On a PUT, read request-only intent from `$api->httpPayload`, never from the merged
+  record.** The merged record always carries `isApproved` from the **existing DB row**, so a guard
+  that read it there treated a plain manager reassignment as a **false approval**. The stubbed suite
+  caught this during development - it is the concrete payoff of the stub-the-DB pattern.
+- **A real-database suite must SKIP on a missing fixture, not FAIL.** Local prod copies differ
+  between developers; a suite that hard-fails when a specific order is absent gets ignored, and an
+  ignored suite protects nothing.
+
 ## Change history
+- 2026-09-11 - **Corrected the run story and added the three-suite pattern.** `_underscore` has no
+  PHPUnit binary, so suites are **standalone scripts** run as `php Test/<path>.php` (exit 0 = pass).
+  The Compass step-1 approval guard shipped three complementary suites in `_underscore/Test/Compass/`
+  (branch `TRUE-81900`): a **stubbed** one that fakes `_Query` and covers every branch, a
+  **real-database** one that runs the generated SQL against a local prod copy and reports **SKIP**
+  when fixtures are missing, and a **replay sweep** that re-decides 6,000 real approvals and compares
+  each verdict against plain SQL. **Mutation testing** (three deliberate breaks, all caught) was used
+  to prove the suite detects regressions. Recorded the real bug the stubbed suite found: on a PUT the
+  merged record always carries `isApproved` from the DB row, so reading it there instead of
+  `$api->httpPayload` turns a manager reassignment into a false approval. (bala)
 - 2026-08-10 — Noted that the stub + reflect-into-privates pattern also carries to **worker2 actions**
   driven from the `test` repo (`test/@Bala/tests/netsuite_salesorder_payload_tests.php`, 76 tests,
   plain PHP, loading the real `Worker/Netsuite/SalesOrder.php`) — a second worked example of testing

package/knowledge/2.0/apps/api2/features/api-payload-interceptors.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-09-02
+updated: 2026-09-11
 owners: ["mhammontree", "dfranks", "bala", "snaredla", "jcardinal"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -623,6 +623,13 @@ and the failing environment**. It is a small table, and the drift is usually exa
   specifics belong in `_Model_<Slug>_X` overrides + interceptor hooks, **not** in `V2.php`.
 
 ## Change history
+- 2026-09-11 - Live instance of the "not registered = dead code" rule: `recordId 179`
+  (approval-decisions) carried only PRE/PUT, POST/PUT and POST/POST in **both** Compass tenants, so a
+  newly added `_Model_Compass_ApprovalDecision::prePost()` would never have run and would have raised
+  **no error**. `dbchanges2/Client_Compass/2026-09-10b - RegisterApprovalDecisionPrePostInterceptor.sql`
+  and its `Client_CompassCanada` twin add the PRE/POST row, `NOT EXISTS`-guarded so they are safe to
+  re-run. Checking the registration table **before** writing a new hook is the cheap step that avoids
+  this. (bala)
 
 - 2026-09-02 — Recorded the **deliberate shared-model exception**: a hook may live on
   `_Model_Client_X` when the behaviour is client-agnostic and the interceptor row is the gate (no row,

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/action-button-rule-engine.md

@@ -6,13 +6,15 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-08-31
-owners: [apeterson]
+updated: 2026-09-11
+owners: [apeterson, bala]
 files:
   - toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts
   - toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.test.ts
   - toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts
   - toga25-supply/src/layout/RecordApprovalModal/view/ApprovalFlowDetailInputs.tsx
+  - toga25-supply/src/layout/RecordApprovalModal/view/ApprovalFlowForm.tsx
+  - toga25-supply/src/surface/evaluateSurfaceRule.ts
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/FIELDS/COMPASS/approvalActionFields.json
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/FIELDS/COMPASSCANADA/approvalActionFields.json
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx
@@ -151,7 +153,38 @@ Retire the shim once all configs express flags as `Rule`.
   comparison must stay config-only; adding to `NAMED_RULES` is the rare exception, not the
   default.
 
+- **⚠ A named rule must use a TRUTHY check, never `!== null`.** `stepTwoAssigned` tested
+  `stepTwo.AssignedTo?.uuid !== null`, which is **true** when the API omits `AssignedTo` altogether
+  (`undefined !== null`) - so a missing step-2 manager *enabled* the Approve button and let an admin
+  strand the order. Now a truthy check on the uuid. The `poNumberEntered` rule directly below it
+  already carried a comment warning about this exact trap. The matching server-side guard is in
+  [Compass Approval-Decision Flow](../../../clients/compass-usa/features/approval-decision-flow.md).
+- **⚠ The evaluator is DUPLICATED in the surface layer.** `src/surface/evaluateSurfaceRule.ts`
+  holds its own copy of the named rules and had the identical `!== null` bug. A change to a named
+  rule must be made in **both** files - fixing one is not a fix.
+- **Resolving a flag is not the same as gating the submit.** `isApproveButtonEnabled` disabled the
+  approve controls but **not Save Changes**, and "Approve All Stages" writes the decision straight
+  into form state, so a blocked approval still posted. `ApprovalFlowForm.tsx` now gates the Save
+  button **and** `handleValidSubmit` on an `isApprovalBlocked` flag, which requires **both** that
+  approving is disabled **and** that the approve is *newly* selected - compared against
+  `defaultValues`, because a stage approved earlier already defaults to `"1"`. The disabled Save
+  reuses the existing tooltip.
+- **`stepTwoAssigned` is configured only for COMPASS and COMPASSCANADA** (`approvalActionFields.json`).
+  DEFAULT and QUAD gate Approve on `order.purchaseOrderDetails.uuid` instead, so a change to this
+  rule cannot reach them.
+
 ## Change history
+- 2026-09-11 - **Fixed `stepTwoAssigned` reading a missing assignee as assigned.** The rule tested
+  `stepTwo.AssignedTo?.uuid !== null`, which is true when the API omits `AssignedTo` entirely, so the
+  Approve button was enabled on orders with no step-2 manager and admins stranded four prod orders.
+  Changed to a truthy uuid check, **in both** `helpers/evaluateEnableRule.ts` and the duplicate copy
+  in `src/surface/evaluateSurfaceRule.ts`. Also gated **Save Changes** (and `handleValidSubmit`) in
+  `ApprovalFlowForm.tsx` on a new `isApprovalBlocked` flag - disabling only the approve controls was
+  not enough, because "Approve All Stages" writes the decision into form state and the save still
+  posted; the flag compares against `defaultValues` so a previously approved stage is not treated as
+  a new approval. Affects COMPASS and COMPASSCANADA only; DEFAULT/QUAD gate on
+  `purchaseOrderDetails.uuid`. Ticket TRUE-81900. **Uncommitted on `_production` at capture time.**
+  (bala)
 - 2026-08-31 — **Added named rule `stepOneUndecided` and extended `buildPatchedTenantFields` to
   resolve flags on `approvalWorkflow.stages[].inputs[]`**, so a VIP-pre-approved step-2 manager can
   be reassigned (Compass USA + Compass Canada). `ApprovalFlowDetailInputs` now treats a resolved

package/knowledge/2.0/apps/toga25-supply/features/record-modals-and-nested-tables.md

@@ -6,8 +6,8 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-09-04
-owners: [apeterson, tcox, jcardinal]
+updated: 2026-09-11
+owners: [apeterson, tcox, jcardinal, bala]
 files:
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx
@@ -358,7 +358,37 @@ Scaffold per the `ItemRecordModalLayout` pattern (`src/layout/ItemRecordModalLay
   [v2-rest-query-contract](../../api2/features/v2-rest-query-contract.md) and
   [Transfer Orders page](transfer-orders-page.md).
 
+- **⚠ The approval modal has TWO approve paths, and the payload shape tells them apart.**
+  Both are dispatched from `RecordApprovalModal/hooks/useApprovalDecisionsMutation.ts`:
+  - `type: "single"` (the green per-stage tick) goes through `makeApprovalDecision` /
+    `updateApprovalDecision` in `api/approvalDecisionsApi.ts` and sends `isApproved` as a
+    **boolean** plus a `note` field.
+  - `type: "workflow"` ("Approve All Stages" / Approval Workflow) goes through
+    `helpers/handleFormatApprovalWorkflowPayload.ts` and sends `isApproved` as the **string `"1"`**
+    with **no** note.
+
+  That difference is how you tell from `Logs_<Tenant>.Api` which button a user actually pressed -
+  the first step in any approval investigation, and the reason a bug can live in one path only.
+- **⚠ The single-stage approve must NOT send `assignedToUserId`.** `makeApprovalDecision()`
+  and `updateApprovalDecision()` hardcoded `assignedToUserId: { uuid: userUuid }`, so every
+  green-tick approve re-sent the **logged-in user** as the stage assignee whether or not anyone
+  touched the field. An admin approving the manager stage therefore **overwrote the real manager
+  with themselves**, and the order timeline then read "Manager Approved" - it looked like the
+  manager had approved. Removed from both functions; `decidedByUserId` already records who approved.
+  The workflow path was always correct (it sends the assignee only when it actually changed), which
+  is exactly why the bug never reproduced through "Approve All Stages". Real orders: SA136901,
+  SA136807, SA137080. Client context:
+  [Compass Approval-Decision Flow](../../../clients/compass-usa/features/approval-decision-flow.md).
+
 ## Change history
+- 2026-09-11 - ⚠ **Removed the hardcoded `assignedToUserId` from the single-stage approve
+  payload** (`approvalDecisionsApi.ts`). Every green-tick approve was re-sending the logged-in user
+  as the stage assignee, so an admin approving the manager stage silently replaced the real manager
+  and the timeline then read "Manager Approved" (prod: SA136901, SA136807, SA137080). Also recorded
+  the **two approve paths and their differing payload shapes** (`single` = boolean `isApproved` +
+  `note`; `workflow` = string `"1"`, no note), which is how the two are told apart in
+  `Logs_<Tenant>.Api` and why the workflow path never showed the bug. Ticket TRUE-81900.
+  **Uncommitted on `_production` at capture time.** (bala)
 - 2026-09-04 — Added the Pattern 6 gotcha that the **item modal's VIEW is Surface-driven while its
   EDIT is still JSON**: a field visible only in edit mode means a missing client `SurfaceOverride`,
   not a data bug (found on Compass's "Restrict to Persona" field). Detail in

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/worker2/features/netsuite-transferorder-outbound-push.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-09-10
+updated: 2026-09-14
 owners: ["bala"]
 files:
   - worker2/Worker/Netsuite/SalesOrder.php
@@ -47,9 +47,16 @@ re-read this doc if you last saw it on 2026-09-02: **the NetSuite customer is th
 destination location**, and `description` is now sent as the NetSuite **`memo`**. Committed as
 worker2 **`cbafd25`** on `_production` and deployed.
 
-**A third correction is written but NOT yet deployed (2026-09-09): the push was sending no ship-to
-address at all**, so NetSuite used the customer's default site on every order. That fix and the
-depth-6 read it needs are below.
+**Deployed 2026-09-14 and confirmed working end to end.** Two more things landed since 2026-09-08
+and are the reason to re-read this doc:
+
+1. **The push was sending no ship-to address at all**, so NetSuite used the customer's default site
+   on every order. Fixed by reading the destination Location's address, which needs a depth-6 read.
+2. **Sending that address then broke every create with an HTTP 400 tax error** from 2026-09-09 to
+   2026-09-14. The cause was **NetSuite customer data, not code** — the customer still carried the
+   retired tax group **-8**. Read
+   [the tax-item section](#-the-customers-netsuite-tax-item-must-be-avatax-or-every-create-400s)
+   before you touch anything tax related here, and before onboarding a new client to this push.
 
 ## Key files / entry points
 
@@ -104,11 +111,11 @@ status columns, so none are sent.
 | `tranDate` | `dateOrder`, date only; **omitted** when null |
 | `otherRefNum` | the PO number (the developer's explicit requirement) |
 | `memo` | `TransferOrders.description` — the NYCHH custom form renders it as **"ORDER DESCRIPTION"** |
-| `shippingAddress` | the **destination** Location's `primaryLocationAddress.address` (added 2026-09-09, not yet deployed). The key is **omitted** when the destination has no address, so NetSuite keeps its own default instead of getting an empty one. |
+| `shippingAddress` | the **destination** Location's `primaryLocationAddress.address` (added 2026-09-09, live 2026-09-14). The key is **omitted** when the destination has no address — and **omitting it is a bug, not a safe default**: NetSuite then ships to the customer's default site. See below. |
 | `externalId` | `toga-to-<transfer order uuid>` |
 | line `item` / `quantity` | each transfer-order item |
 | line `rate` | **0** — this is the zero-value part |
-| line `location` | the **origin** warehouse |
+| line `location` | the **origin** warehouse. **`location` is NOT a ship-to** — NetSuite never uses a line's location for delivery. |
 
 ### ⚠ Destination = CUSTOMER, origin = WAREHOUSE (this was built backwards first)
 
@@ -146,6 +153,12 @@ no NetSuite customer for.
 > multi-site tenant those are different NetSuite records, and the difference is invisible until
 > someone picks the non-default site.
 
+**A consequence worth knowing before you go hunting in supply:** `resolveTransferOrderCustomer()`
+always lands on the **client's** customer, so **changing the destination location cannot change the
+NetSuite customer**. When a problem is customer-level (a tax item, a hold, a wrong subsidiary),
+picking a different destination site is not a workaround — the destination only supplies the
+ship-to address.
+
 **Verified live 2026-09-08 on SO 289187 (id 7463537):** destination Woodhull (customer **31925**),
 customer on the NetSuite order came out **4490 / NYC Health + Hospitals**, and ORDER DESCRIPTION
 showed the transfer order's `description`.
@@ -155,7 +168,7 @@ destination whose customer id already equals the client's own (**30205** and **3
 and new rules produce the same id for them.
 
 
-### ⚠ The ship-to address was NEVER sent — and it needs a depth-6 read (fixed 2026-09-09, not deployed)
+### ⚠ The ship-to address was NEVER sent — and it needs a depth-6 read (fixed 2026-09-09, live 2026-09-14)
 
 `buildSalesOrderShapeFromTransferOrder()` never set a `shipToAddress` key, and the `shippingAddress`
 block in `buildNetSuiteOrder()` (~L922) only runs when that key exists. So **every transfer order
@@ -210,6 +223,35 @@ null, and the code fix would have been a **silent no-op**. Fixed by
 > row drops the branch silently instead of erroring — see
 > [nested FK ACL embedding](../../api2/features/nested-fk-acl-embedding.md).
 
+#### ⚠ Dropping the address is NOT a workaround — NetSuite ships to the customer default, silently
+
+When the payload omits the ship-to address the create **succeeds**, so it looks like a fix. It is
+not. NetSuite falls back to whichever entry in the **customer's** address book is flagged
+`defaultshipping = T`, with no warning anywhere in the response. Because the customer is the client's
+whole account (previous section), that is one fixed site for **every** destination — NYCHH customer
+28908 has **124** saved addresses and the default is *NYCHHC Jacobi Dental* (address id 6568575,
+1400 Pelham Parkway South, Bronx NY 10461). **5 of the 6** transfer orders that reached NetSuite
+before the fix shipped there regardless of their real destination (orders 7453238, 7462009, 7463537,
+7467799, 7482373); only 7462031 was right, and only by accident — it predates the switch to the
+parent customer and was built on destination sub-customer 33674, whose own default happens to be the
+destination.
+
+> **Durable rule: "drop the address to get past the 400" is a wrong-address bug, not a fix.** A
+> successful create proves nothing about where the goods go. And the line-level `location` does not
+> save you — that is the **source** warehouse (NetSuite internal id 117 for NYCHH) and NetSuite never
+> uses it for delivery.
+
+#### Depth 6 is verified, and there is a decoy branch next to it
+
+`_Model_Client_TransferOrder::NETSUITE_READ_DEPTH = 6` was checked against the raw
+`Core.WorkerJobs.parameters` blob of a real job, not just reasoned about: at 6 the full
+`destinationLocation.primaryLocationAddress.address.state.country` branch comes through.
+
+**The decoy:** the same payload also carries `contact.contactLocations[].location...address`, and
+*that* branch runs out of depth and has **no `state`**. If you are debugging a missing state or
+country, check which branch you are reading before you raise the depth again — the destination
+branch is complete.
+
 ### `description` → `memo` cannot leak into a plain sales order
 
 `memo` is sent only from the transfer-order shape. There is **no `memo` RecordField and no `memo`
@@ -229,6 +271,76 @@ bridge first** (that is what the Create Transfer Order modal writes), and falls
 [SO↔PO bridge direction](../../_underscore/features/sales-order-purchase-order-bridge-direction.md)
 for why the bridge, not the column, is the real source.
 
+## ⚠ The customer's NetSuite tax item must be AVATAX, or every create 400s
+
+**Symptom.** Every transfer order create fails with NetSuite HTTP **400**:
+
+```
+Error while accessing a resource. Invalid shippingtaxcode reference key -8 for subsidiary 1.
+```
+
+`Core.WorkerJobs` ids **1534082, 1534805, 1535235, 1536824, 1536920** (all 2026-09-14). It started on
+**2026-09-09**, the day the push began sending a ship-to address, and it blocked **every** transfer.
+
+**Cause — customer data, not code.** NetSuite customer **28908** (NYC Health + Hospitals, the
+client-level customer from `Core.Clients.netsuiteCustomerInternalId`) still carried the **retired tax
+group -8** as its `taxitem`. When an order carries an **inline ship-to address**, NetSuite rebuilds
+the address on the order and re-checks the shipping tax code against **subsidiary 1**; `-8` fails that
+check and the whole create is rejected. No address, no re-check — which is exactly why this only
+appeared once the address fix went in.
+
+**Fix.** NetSuite ops changed `taxitem` on customer **28908** from `-8` to **5050 (AVATAX)**. No code
+change. Verified working the same day. This is the normal value here: **7151** of subsidiary 1's
+customers are already on 5050, and only **61** are still on -8.
+
+> **Durable rule: before a new client's first transfer order, check that its NetSuite customer's
+> `taxitem` is 5050 AVATAX.** This is an onboarding step, not a bug to debug later — the first order
+> for any customer still on -8 will fail with the message above.
+
+### ⚠ Pinning `taxItem` / `shippingTaxCode` in the payload does NOTHING
+
+This cost several failed attempts, so it is written down in the code as well (comment in
+`buildNetSuiteOrder()` just below the `shippingAddress` block):
+
+- **NetSuite derives both fields from the customer AFTER applying the address and discards whatever
+  we send.** Proven twice: jobs **1534805** and **1536824** both sent `-7` and both still failed
+  reporting **-8**.
+- **Stripping `state` and `country` from the shipping address does not help either** (job
+  **1535235**). *Any* inline address at all triggers the re-check.
+
+A `NETSUITE_TAX_CODE__NOT_TAXABLE = '-7'` constant and its pin block were added and then **removed
+again**. A comment now sits in their place warning not to re-add them. **Do not re-add them.**
+
+### ⚠ -8 is NOT a dead id — it lives in `taxgroup`, not `salestaxitem`
+
+An earlier code comment claimed -8 "points at nothing". **That was wrong**, and it sent the debug off
+in the wrong direction:
+
+| Id | Name | Table |
+|---|---|---|
+| **-8** | `-Not Taxable-` | **`taxgroup`** — exists and is **active** |
+| **-7** | `-Not Taxable-` | **`salestaxitem`** |
+
+Two different tables, the same display name. **Checking only `salestaxitem` for a tax code id will
+tell you it does not exist when it does.** Query both before concluding an id is dead — SuiteQL
+details in [NetSuite SuiteQL API reference](../../../../1.0/apps/library/features/netsuite-suiteql-api-reference.md).
+
+### Who else is still on -8 (scanned 2026-09-14, re-check before onboarding)
+
+**61** NetSuite customers on subsidiary 1 remain on tax group -8. The ones that touch Toga:
+
+| NetSuite customer | Who | Risk today |
+|---|---|---|
+| **34283** Yale New Haven Health | a **client-level** customer in `Core.Clients` | will fail its **first** transfer order; client DB has **0** transfer orders today |
+| **2661** Endeavor Health | a **client-level** customer in `Core.Clients` | same — **0** transfer orders today |
+| **31584** Coney Island | a NYCHH **sub-customer** in `Client_Nychh.Customers` | dormant, **0** sales orders |
+| **1101** Miami-Dade Police Department | used by `Client_Miamidade` | nothing failing today |
+| **32030** Security 101 | used by `Client_Miamidade` | nothing failing today |
+
+All **17** other NetSuite customer ids used by `Client_Nychh` are already on **5050 AVATAX**. A scan of
+`Core.WorkerJobs` shows this error has only ever hit the transfer-order action — 5 jobs, all on
+2026-09-14.
+
 ## The trigger — `postPost` on the SHARED `_Model_Client_TransferOrder`
 
 `_Model_Client_TransferOrder::postPost` queues the action. **Not** `_Model_Nychh_TransferOrder` — a
@@ -363,8 +475,11 @@ Stub detail for anyone extending it: `_Model_True` is stubbed with **only** the
   `postPost` reads **zero lines** and the push aborts — the trigger would then have to move. See
   [Transfer Orders page](../../toga25-supply/features/transfer-orders-page.md).
 - **dev-sandbox metadata is incomplete** (record 325 + its RecordFields + both inherent-child rows).
-- **The ship-to fix is written, `php -l` clean, but NOT deployed and NOT committed** (worker2 +
-  `_underscore`). The two NYCHH SQL files it depends on **have** been run on prod.
+- ~~**The ship-to fix is written but NOT deployed.**~~ **Closed 2026-09-14** — deployed, and
+  confirmed working by the developer after NetSuite customer 28908 moved off tax group -8.
+- **The -8 tax-group list is a snapshot (2026-09-14).** Re-run the check before onboarding any new
+  client to this push; **34283 Yale New Haven Health** and **2661 Endeavor Health** are the two that
+  will fail on their first order.
 - **Undecided: should the delivery contact go into the NetSuite `attention` field?** NetSuite ship-to
   addresses carry a person on the first line (order **289193** shows *Frederick Roberts*, the Bellevue
   delivery contact). `TransferOrders.contactId` exists as an FK on `_Model_Client_TransferOrder` but
@@ -390,6 +505,9 @@ Stub detail for anyone extending it: `_Model_True` is stubbed with **only** the
   a lost PO number aborts the push. Do not "optimise" the depth.
 - **This action does not retry itself**, exactly like the sales-order push: a throw records
   `isSuccess = 0` and stops. An event-triggered push fires once.
+- **A NetSuite HTTP 400 naming a tax code is a CUSTOMER data problem, not a payload problem.** Check
+  the customer's `taxitem` first; do not try to pin the tax fields in the payload (they are ignored)
+  and do not drop the address to make the error go away (that silently ships to the wrong site).
 - **`git diff --stat` after any programmatic full-file write to `_underscore`.** A full-file write
   with an editor default flipped CRLF → LF on `_underscore/Model/Nychh/TransferOrder.php` — content
   identical, git reported it modified with no content hunks. Restored with `git checkout --`. The
@@ -397,6 +515,30 @@ Stub detail for anyone extending it: `_Model_True` is stubbed with **only** the
 
 ## Change history
 
+- 2026-09-14 — **Deployed the ship-to fix, then spent the day on the 400 it exposed. Root cause was
+  NetSuite customer data.** From 2026-09-09 every transfer order create failed with *"Invalid
+  shippingtaxcode reference key -8 for subsidiary 1"* (`Core.WorkerJobs` 1534082, 1534805, 1535235,
+  1536824, 1536920). NetSuite customer **28908** still carried the retired tax group **-8**; sending
+  an inline ship-to address makes NetSuite rebuild the address and re-check the shipping tax code
+  against subsidiary 1, and -8 fails it. **NetSuite ops moved 28908's `taxitem` from -8 to 5050
+  (AVATAX)** — no code change, and the push was confirmed working end to end. Recorded three things
+  that cost real time: **pinning `taxItem`/`shippingTaxCode` in the payload is ignored** (NetSuite
+  derives both from the customer *after* the address — jobs 1534805 and 1536824 both sent -7 and both
+  still failed on -8), so the `NETSUITE_TAX_CODE__NOT_TAXABLE = '-7'` constant and its pin block were
+  added and then removed with a warning comment left behind; **stripping `state`/`country` does not
+  help either** (job 1535235) because any inline address triggers the re-check; and **-8 is not a dead
+  id** — it is active in `taxgroup` as "-Not Taxable-", while `salestaxitem` holds -7 with the same
+  name, so an earlier comment claiming it "points at nothing" was wrong. Also documented that
+  **omitting the address is a wrong-address bug, not a fix**: NetSuite silently uses the customer's
+  `defaultshipping = T` entry (28908 has 124 addresses; the default is Jacobi, id 6568575), which is
+  why 5 of the 6 orders that reached NetSuite went to the wrong site. Confirmed the line `location` is
+  the source warehouse (117) and is never a ship-to; that `resolveTransferOrderCustomer()` always
+  lands on the client's customer, so changing the destination cannot work around a customer-level
+  problem; and that `NETSUITE_READ_DEPTH = 6` really does carry
+  `destinationLocation.primaryLocationAddress.address.state.country` (verified against a real job's
+  `parameters` blob), while the neighbouring `contact.contactLocations[]` branch runs out of depth and
+  is a decoy. Added the dated list of the **61** customers still on -8, of which **34283 Yale New Haven
+  Health** and **2661 Endeavor Health** are client-level and will fail their first transfer order. (bala)
 - 2026-09-09 — **The push had never sent a shipping address at all.**
   `buildSalesOrderShapeFromTransferOrder()` set no `shipToAddress` key, so the `shippingAddress` block
   in `buildNetSuiteOrder()` never ran and NetSuite substituted the **customer's default** site on every

package/knowledge/clients/compass-usa/features/approval-decision-flow.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-08-31
+updated: 2026-09-11
 owners: ["apeterson", "dfranks", "bala"]
 files:
   - _underscore/Model/Compass/ApprovalDecision.php
@@ -15,6 +15,7 @@ files:
   - _underscore/Model/Compass/Canada/ApprovalDecision.php
   - _underscore/Model/Client/ApprovalTemplateStage.php
   - _underscore/Model/Quad/SalesOrder.php
+  - dbchanges2/Client_Compass/2026-09-10b - RegisterApprovalDecisionPrePostInterceptor.sql
 related:
   - mr-ma-order-approval-and-status.md
   - ../../../2.0/apps/toga25-supply/features/action-button-rule-engine.md
@@ -241,6 +242,38 @@ break the invariant and produce a stage with two competing approvers. Both exist
 paths already respect this (`_Model_Compass_SalesOrder` compares `assignedToUserId != managerId` and
 then PUTs).
 
+### Step-1 approval is blocked when step 2 has no assignee (guard - BUILT, NOT DEPLOYED)
+
+An admin could approve step 1 on an order whose step-2 stage had **no `assignedToUserId`**. The
+order then moved to *Pending Approval* assigned to nobody: no manager approval-request email is
+sent (that email is addressed from the step-2 assignee), nobody can act on it, and **no report
+surfaces it** - the order just goes silent. Real prod population: **SA136795, SA137088, SA137146,
+SA137235**.
+
+`_Model_Compass_ApprovalDecision` now carries a `prePost()` plus an extended `prePut()` that reject
+a **step-1 approval** when the step-2 stage has no `assignedToUserId`, throwing
+`_Exception_Validation` (api2 maps it to **HTTP 400**). Both tenants are covered automatically,
+because the subclasses are empty.
+
+**Every exemption is decided from the database, never from the request payload:**
+
+- **MR/MA orders** - matched on the `SalesOrders.number` prefix; see
+  [MR/MA order approval and status](mr-ma-order-approval-and-status.md).
+- **Step-2 decisions** - identified by the stage's step number, not by anything the caller sends.
+- **Templates that define no step 2** - nothing can strand, so nothing is blocked.
+
+Verified by replaying **6,000 real approvals** against a local copy of prod: 4,209 normal approvals
+and 1,786 MR/MA auto-approvals allowed, only the genuinely stranded orders blocked. Compass Canada:
+760 approvals, **none** blocked.
+
+**⚠ The guard does nothing until its interceptor row exists.** A `prePost` only runs when a
+matching `ApiPayloadInterceptors` row is registered, and `recordId 179` (approval-decisions) carried
+only PRE/PUT, POST/PUT and POST/POST - a newly added `prePost` is **dead code with no error**.
+`dbchanges2/Client_Compass/2026-09-10b - RegisterApprovalDecisionPrePostInterceptor.sql` (and the
+`Client_CompassCanada` twin) insert the PRE/POST row, guarded with `NOT EXISTS` so they are safe to
+re-run. **Run both, then deploy api2** - otherwise nothing changes. Mechanics:
+[API Payload Interceptors](../../../2.0/apps/api2/features/api-payload-interceptors.md).
+
 ### Manager reassignment and the notification list
 When a step-2 (Manager) approval decision is **reassigned** to a new manager,
 `_swapManagerEmailAddress()` updates the order's CC/notification list in `SalesOrderEmailAddresses`:
@@ -436,7 +469,56 @@ requester**. All of these comparisons are case-insensitive (`strcasecmp()`), mat
   could not open the order from the "Manager Approval Needed" email, so admin Kai Wong had to
   approve as manager on his behalf. (Fixed 2026-07-23.)
 
+- **⚠ An exemption from a server-side guard must be decided from the DATABASE, never from a
+  client-supplied field.** The step-1 guard above originally skipped itself when the request payload
+  carried `approvalDecisionType` / `approvalDecisionTypeId`, treated as a "this is a system
+  auto-approval" marker. That value comes from the **request body**, so any caller could set it and
+  skip the check entirely. The early return and its `_isSystemAutoApproval` helper were removed in
+  PR review. Checked against prod before removing: all **5,028** step-1 auto-approvals in Compass
+  history are MR/MA orders (Canada has none), so the DB-backed order-number check covers every real
+  case, and VIP auto-approvals land on **step 2** and exit at the step check. Treat this as the
+  general rule for any guard added here.
+- **⚠ The green approve tick used to silently replace the step-2 manager with the approver.**
+  `makeApprovalDecision()` / `updateApprovalDecision()` in supply hardcoded
+  `assignedToUserId: { uuid: userUuid }` into every single-stage approve payload, so an admin
+  approving the manager stage **overwrote the real manager with themselves** - and the order
+  timeline then read "Manager Approved", making it look like the manager had acted. Confirmed on
+  **SA136901** (07:18:35 re-sent an assignee that had not changed; Dawn Anderson had already been
+  assigned by Emily at 06:50:06), and it also hit **SA136807** (Angel Almodovar replaced) and
+  **SA137080** (delegate manager Daniel Mezzanares replaced). Fixed front-end by removing the field
+  - `decidedByUserId` already records who approved. The "Approve All Stages" path was always
+  correct, which is why the bug never reproduced there. Detail:
+  [Record Modals & Nested Tables](../../../2.0/apps/toga25-supply/features/record-modals-and-nested-tables.md).
+- **⚠ A manager swap sent in the SAME save as an approval is never logged, and the email list
+  keeps the old manager.** `_evaluateManagerVip()` returns immediately when the request carries
+  `isApproved`, on the assumption that a request is *either* an assignment *or* an approval. When
+  both arrive together the `"Manager reassigned"` note is skipped (the feature itself works - it has
+  fired **757** times since May) **and** so is the `SalesOrderEmailAddresses` swap, so the outgoing
+  manager stays on the notification list. A handler for the combined case was drafted on the
+  `_sandbox-client` branch only and is **NOT** on `TRUE-81900` - known gap, not shipped.
+- **The upstream cause of an unassigned step 2 is a user saved with no `supervisorUserId`.** The
+  admin add-user screen allows saving a user without one, and the PEOPLE-file import may or may not
+  backfill it later. That one data hole feeds both the `!$hasManager` wipe above and the
+  never-created step-2 decision at order creation. **Not fixed** - the guard only stops the order
+  being *stranded*, it does not give it a manager.
+
 ## Change history
+- 2026-09-11 - **Blocked step-1 approval when step 2 has no assignee** (`prePost()` + extended
+  `prePut()` on `_Model_Compass_ApprovalDecision`, `_Exception_Validation` -> HTTP 400), after four
+  prod orders (SA136795, SA137088, SA137146, SA137235) sat in *Pending Approval* assigned to nobody
+  with no email sent and no report surfacing them. Exemptions are **all DB-derived** - MR/MA by
+  `SalesOrders.number` prefix, step-2 decisions by step number, templates with no step 2 - after PR
+  review **removed a client-controlled bypass** that skipped the guard whenever the request payload
+  carried `approvalDecisionType`/`approvalDecisionTypeId` (prod check: all 5,028 historic step-1
+  auto-approvals are MR/MA, Canada none). Verified by replaying 6,000 real approvals from a local
+  prod copy (4,209 normal + 1,786 MR/MA allowed; Canada 760, none blocked). Also recorded: the green
+  approve tick was **overwriting the step-2 manager with the approver** (SA136901 / SA136807 /
+  SA137080) until `assignedToUserId` was removed from the single-stage payload, and that
+  `_evaluateManagerVip()` skips both the "Manager reassigned" note and the
+  `SalesOrderEmailAddresses` swap when an assignment and an approval arrive in one save (drafted on
+  `_sandbox-client` only, **not shipped**). Ticket TRUE-81900. **NOT DEPLOYED** - the `2026-09-10b`
+  interceptor SQL must run on `Client_Compass` **and** `Client_CompassCanada`, and api2 must be
+  deployed, before the guard does anything. (bala)
 - 2026-08-31 — **Root-caused the "decided but untyped" step-2 approvals that no admin can recover**
   (both tenants, via the shared parent). `_Model_Compass_SalesOrder::postPut`'s `!$hasManager` branch
   nulls the entire step-2 decision when the "Order for" contact has no `supervisorUserId`; a

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/knowledge/clients/nychh/features/transfer-order-netsuite-push.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: nychh
 type: client-feature
 status: active
-updated: 2026-09-10
+updated: 2026-09-14
 owners: ["bala"]
 files:
   - _underscore/Model/Client/TransferOrder.php
@@ -33,7 +33,13 @@ and live in
 this doc holds the NYCHH-specific parts: the interceptor row, the **location → mapping-column
 roles** (verified in production), and the data/metadata state the push still needs.
 
-**LIVE since 2026-09-08.** NetSuite SO **289187** (internal id 7463537) was created from this path
+**LIVE since 2026-09-08, fully working since 2026-09-14.** Between 2026-09-09 and 2026-09-14 **every**
+transfer order failed on a NetSuite tax error caused by customer **28908**'s data — see
+[the tax item section](#-customer-28908-was-stuck-on-tax-group--8-and-it-blocked-every-transfer) —
+and before that, every order shipped to the wrong hospital. Both are now fixed and the push was
+confirmed working by the developer.
+
+NetSuite SO **289187** (internal id 7463537) was created from this path
 and is correct. The location-role table below still stands, but **the destination location is NOT
 the NetSuite customer** — that was corrected the same day; see the next section.
 
@@ -118,6 +124,34 @@ rows for records 69, 12, 23, `NOT EXISTS`-guarded). **Run on prod and verified:
 > Generalised on [nested FK ACL embedding](../../../2.0/apps/api2/features/nested-fk-acl-embedding.md):
 > deepening a `depth` is an ACL change, and the branch is dropped **silently**.
 
+## ⚠ Customer 28908 was stuck on tax group -8, and it blocked every transfer
+
+From **2026-09-09** (the day the push started sending a ship-to address) to **2026-09-14**, every
+NYCHH transfer order create returned NetSuite HTTP **400**:
+
+```
+Error while accessing a resource. Invalid shippingtaxcode reference key -8 for subsidiary 1.
+```
+
+`Core.WorkerJobs` ids **1534082, 1534805, 1535235, 1536824, 1536920**.
+
+**It was NetSuite customer data, not Toga code.** Customer **28908** (NYC Health + Hospitals — the
+client-level customer from `Core.Clients.netsuiteCustomerInternalId`, which every NYCHH transfer order
+uses) still carried the retired tax group **-8** as its `taxitem`. An inline ship-to address makes
+NetSuite rebuild the address on the order and re-check the shipping tax code against subsidiary 1,
+and -8 fails that check.
+
+**Fix: NetSuite ops changed 28908's `taxitem` from -8 to 5050 (AVATAX).** Verified working the same
+day. 7151 of subsidiary 1's customers were already on 5050.
+
+**Still on -8 inside NYCHH: sub-customer 31584 "Coney Island"** (present in `Client_Nychh.Customers`,
+0 sales orders today, so dormant). All **17** other NetSuite customer ids used by `Client_Nychh` are
+on 5050. The mechanism, the failed workarounds, and the cross-client -8 list are on
+[the shared push doc](../../../2.0/apps/worker2/features/netsuite-transferorder-outbound-push.md).
+
+> **Do not try to fix this from supply.** The customer is always the client (28908), so **changing the
+> destination location cannot change the NetSuite customer** — it only changes the ship-to address.
+
 ## Where the ship-to address comes from — and the location-2 problem
 
 The address is the **destination Location's** `primaryLocationAddress.address`. Until 2026-09-09 all
@@ -130,6 +164,21 @@ are in [location shipping addresses + delivery contacts](./location-shipping-add
 delivery site for that location — and location 2 is the destination on the large majority of NYCHH
 transfer orders. Any transfer order to location 2 will ship to Jacobi.
 
+### What "no address" actually did — 5 of 6 orders went to the wrong hospital
+
+Customer **28908** holds **124** saved addresses, and the one flagged `defaultshipping = T` is
+**“NYCHHC Jacobi Dental”** (address id **6568575**, 1400 Pelham Parkway South, Bronx NY 10461). With
+no address in the payload NetSuite used that one **silently** on every order:
+
+| NetSuite order | Ship-to |
+|---|---|
+| 7453238, 7462009, 7463537, 7467799, 7482373 | **wrong** — Jacobi Dental, whatever the real destination |
+| 7462031 | correct, **by accident** — it predates the switch to the parent customer and was built on destination sub-customer **33674**, whose own default *is* the destination |
+
+The line-level `location` does **not** rescue this: that is the **source** warehouse (NetSuite
+internal id **117**) and NetSuite never uses it for delivery. So dropping the address to get past a
+400 is a wrong-address bug, not a fix.
+
 ## Interceptor registration — record 312, and the deploy order matters
 
 `dbchanges2/Client_Nychh/2026-09-02a - TransferOrderNetsuitePushInterceptor.sql` inserts into
@@ -164,6 +213,19 @@ switch that turns the feature on for NYCHH and nobody else.
 
 ## Change history
 
+- 2026-09-14 — **Push deployed and confirmed working; the blocker was NetSuite customer 28908's tax
+  item.** Every transfer order from 2026-09-09 failed with *"Invalid shippingtaxcode reference key -8
+  for subsidiary 1"* (`Core.WorkerJobs` 1534082, 1534805, 1535235, 1536824, 1536920) because 28908
+  still carried the retired tax group **-8**; sending an inline ship-to address makes NetSuite
+  re-check the shipping tax code against subsidiary 1. **NetSuite ops moved 28908 to 5050 (AVATAX)**
+  and the push worked with no code change. Confirmed the customer is always 28908, so a destination
+  change in supply cannot work around a customer-level problem. Quantified the old no-address
+  behaviour: 28908 has **124** addresses and its `defaultshipping` entry is **Jacobi Dental (id
+  6568575)**, which is why **5 of the 6** orders that reached NetSuite (7453238, 7462009, 7463537,
+  7467799, 7482373) shipped to the wrong hospital — only 7462031 was right, and only because it was
+  built on sub-customer 33674 before the switch to the parent. Remaining NYCHH exposure: sub-customer
+  **31584 Coney Island** is still on -8 but dormant; the other 17 NetSuite customer ids used by
+  `Client_Nychh` are all on 5050. (bala)
 - 2026-09-09 — **The push had never sent a shipping address**, so NetSuite used customer 28908's
   default site on every order: NetSuite order **7467799** was for North Central Bronx yet shipped to
   Jacobi's *1400 Pelham Parkway South*, and SO **289187** (Woodhull) shows the same. The fix reads the

package/package.json

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