toga-ai 1.0.724 → 1.0.726

package/knowledge/1.0/apps/worker/workflows/netsuite-duplicate-items-dedup.md

@@ -111,13 +111,27 @@ duplicates** and must be deployed first — see
 - **`UPDATE IGNORE ...; DELETE ... WHERE fk=dupe` permanently DELETES collision rows** and drops its
   helper maps, so prod cannot self-reverse. A reversal needs a **pre-merge snapshot** restored as a
   scratch DB — plan the backup before running any variant of this.
-- **Blast radius of the 2026-08-31 `duplicate_items_merge_ALL_CLIENTS.sql`:** it ran on 17 clients
-  (Masonite, Ncci, Erau, Shrss, Wmchealth, Trividiahealth, Prudential, Miamidade, Browardsheriff,
-  Nychh, Canon, Quad, Compass, Elite, Growrk, Spglobal, Endeavorhealth). At-risk = two-catalog +
-  TOGa Commerce clients like Compass; a **per-client assessment is outstanding**.
+- **Blast radius of the 2026-08-31 `duplicate_items_merge_ALL_CLIENTS.sql` (assessment complete
+  2026-09-01):** it ran on 17 clients (Masonite, Ncci, Erau, Shrss, Wmchealth, Trividiahealth,
+  Prudential, Miamidade, Browardsheriff, Nychh, Canon, Quad, Compass, Elite, Growrk, Spglobal,
+  Endeavorhealth). **Only 2 were damaged — Compass and Quad, both two-catalog TOGa Commerce
+  clients.** The other 15 needed no reversal: 13 single-catalog "Agilant"-only clients were a
+  legitimate within-catalog dedup, NYCHH mixed Etilize + NetSuite in one catalog (no fold
+  possible), and Prudential was cleared (single populated catalog; NULL `assetType` is its normal
+  state). Triage per client with `Catalogs` LEFT JOIN `Items` (empty catalogs still show) + the
+  pipeline signal (`c_etilizeProductId` = store vs `c_netsuiteInternalItemId` = Agilant); a client
+  is damaged only if it has a two-catalog store/procurement design AND catalog-1 was folded into
+  catalog-2 AND storefront/transmit depends on catalog-1. See the Compass
+  [catalog-fold reversal](../../../clients/compass-usa/workflows/catalog-fold-reversal.md) and
+  [Quad catalog-fold reversal](../../../clients/quad/workflows/catalog-fold-reversal.md).
 
 ## Change history
 
+- 2026-09-01 — **Blast-radius assessment complete.** Of the 17 clients the merge ran on, only 2
+  were damaged — Compass and Quad (both two-catalog TOGa Commerce). The other 15 needed no
+  reversal (13 single-catalog "Agilant"-only = legitimate within-catalog dedup; NYCHH mixed
+  Etilize + NetSuite in one catalog; Prudential cleared — single populated catalog, NULL
+  assetType is normal). Added the durable triage method and linked the Quad reversal. (jcardinal)
 - 2026-09-01 — **⚠ Corrected the success claim.** "0 duplicate part numbers" is NOT a clean-run proof
   for a multi-catalog client. This merge is catalog-blind (groups on `UPPER(partNumber)` only), so for
   Compass it folded 199 intentional catalog-1 store items into their Agilant canonical, broke MITS

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

@@ -4,7 +4,7 @@
 |-----|---------|-------|
 | [Proposed — git-sourced base+overlay JSON authoring for the Surface layer](architecture/surface-authoring-proposal.md) | A **proposal / handoff recommendation** (not implemented) that the Surface layer's *authoring* model move off hand-authored SQL against the `SurfaceOverrides` E | _underscore/Model/Core/Surface.php, _underscore/Model/Client/SurfaceOverride.php |
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
-| [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql, _underscore/Model/Core/Page.php, _underscore/Model/Core/Surface.php, _underscore/Model/Client/TrackingNumber.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission.sql, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql, dbchanges2/Client_Quad/2026-08-24 - Quad Multi Currency Item Pricing.sql, dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql, dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.sql |
+| [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql, _underscore/Model/Core/Page.php, _underscore/Model/Core/Surface.php, _underscore/Model/Client/TrackingNumber.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission.sql, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql, dbchanges2/Client_Quad/2026-08-24 - Quad Multi Currency Item Pricing.sql, dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql, dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.sql, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql |
 | [Address Uniqueness Normalization (unit identifier + 5-digit ZIP comparison)](features/address-uniqueness-normalization.md) | When a business rule says *"only one X per physical address"*, comparing address rows field-for-field does **not** work: the same dwelling is spelled many diffe | _underscore/Model/Rate/Entitlement.php |
 | [Address Validation (carrier waterfall + validateAddress scripted endpoint)](features/address-validation.md) | `_Model_Client_Address::validateAddress` verifies a US address against a **carrier waterfall (USPS → FedEx → UPS)** and returns a single canonical, carrier-norm | _underscore/Model/Client/Address.php, _underscore/Component/Library/Carriers/Usps/Usps.php |
 | [_ApiRequest — JSON encode/decode & api-logging behavior](features/apirequest-json-content-type.md) | `_ApiRequest` is the 2.0 outbound HTTP client. | _underscore/ApiRequest.php |

package/knowledge/2.0/apps/_underscore/features/acl-permission-chain.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
-owners: ["jcardinal", "mhammontree", "tcox", "bala"]
+updated: 2026-09-01
+owners: ["jcardinal", "mhammontree", "tcox", "bala", "apeterson"]
 files:
   - api2/Component/Api/V2/V2.php
   - dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql
@@ -21,6 +21,7 @@ files:
   - dbchanges2/Client_Quad/2026-08-24 - Quad Multi Currency Item Pricing.sql
   - dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql
   - dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.sql
+  - dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql
 ---
 
 ## Summary
@@ -127,8 +128,46 @@ identical in every environment (the platform's only sanctioned hardcoded ids —
 next free id differs per environment (a new field took 2483 in production and 2766 in
 dev-sandbox), so a row you are creating right now may need a per-environment literal.**
 
-**Known-broken existing files (same root cause):** `Client_Rate/2026-07-23a` and
-`Client/2026-07-16c`. A clean local run is never proof either worked.
+**Known-broken existing files (same root cause).** A full sweep of `dbchanges2` on **2026-09-01**
+found **12** `Client/` files doing a real cross-cluster read (`FROM`/`JOIN Core.*`). All of them are
+**ACL or surface-grant** migrations, and all fall in a **2026-06-25 → 2026-07-23** window —
+`Core/` is clean, so the leak is one-directional:
+
+| File (`dbchanges2/Client/`) |
+|---|
+| `2026-07-22c - TrackingNumberMeasureIdsFieldPermission` (10 `Core.` refs) |
+| `2026-07-16b - TrackingNumberSignatureTypeFieldPermission` |
+| `2026-07-16c - AddressValidateScriptAcl` |
+| `2026-07-23a - EntitlementServiceAddressIdFieldPermission` |
+| `2026-07-17 - ItemsisFulfillable` |
+| `2026-07-10b - ItemFulfillmentReturnAddressIdFieldPermission` |
+| `2026-07-10c - GenerateReturnLabelScriptAcl` |
+| `2026-07-02a - TrackingNumberReprintScriptAcl` |
+| `2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission` |
+| `2026-06-30a - SurfaceMetaGroupAcl` |
+| `2026-06-29c - SurfaceRecordScriptAcl` |
+| `2026-06-25c - SurfaceClientAcl` |
+
+(plus `Client_Rate/2026-07-23a`, previously known.) **A clean local run is never proof any of them
+worked** — locally the schema literally named `Core` is the **1.0** database, so the subselect
+resolves against the wrong schema instead of failing.
+
+**Their failure mode is silent, and it is worth stating precisely** because it is why nobody caught
+this for two months: `SET @x = (SELECT … FROM Core.X)` yields **NULL**, the `IS NOT NULL` guard then
+suppresses the `INSERT`, and **the file reports success having granted nothing**. No error, no
+warning, zero rows.
+
+**Confirmed live instance:** `Client_Adyen` has `2026-07-22c`'s mirror sibling grant but **none of
+that file's three measure-id fields** — exactly the shape this bug produces.
+
+Verified on production 2026-09-01: both `reader1.client.database.togahub.com` and
+`writer.client.database.togahub.com` host **only `Client_*` databases — there is no `Core` there
+at all**, so a `Core.X` reference from a `Client/` file cannot resolve under any circumstances.
+
+**New occurrences are now blocked** by the `dbchanges2-cluster-isolation` PreToolUse hook
+(`.claude/hooks/toga/dbchanges2-cluster-isolation.js`), which inspects every `Write`/`Edit`.
+The 12 above pre-date it and are a **remediation backlog**, not a closed issue — each needs its
+`Core` subselect swapped for a hardcoded `Core.RecordFields` id literal and then re-running.
 
 ### Standard field vs. custom (`c_`) field — TWO different permission tables
 
@@ -191,6 +230,33 @@ first (see
   granting access therefore goes in `dbchanges2/Client/` (or a specific `Client_<Name>/`) so it
   runs against every client DB.
 
+### ⚠ Read `aclDatabase` FIRST — querying the wrong database gives a confident, meaningless answer
+
+This is the step that is easiest to skip and the most expensive to skip, because **both databases
+have an `AclFieldPermissions` table**. Query the wrong one and you get rows back, draw a conclusion,
+and never learn it was about a different record. Verified the hard way 2026-09-01: `Core` was
+checked for `purchase-order-items` (`Records.id = 18`), which is **`aclDatabase = 'CLIENT'`** — so
+Core's rows are **never consulted for that record** and the whole investigation went down a wrong
+path on the strength of them.
+
+**Recipe — "a field returns 0/null but the data is there":**
+
+1. **Establish the ACL database before anything else:**
+   ```sql
+   SELECT id, route, aclDatabase FROM Core.Records WHERE route = '<route>';
+   ```
+2. **Query `AclFieldPermissions` in THAT database** — `Core` if `CORE`, `Client_<Tenant>` if
+   `CLIENT`. Rows in the other one are noise.
+3. **Compare a field that WORKS against the broken one, side by side.** A role row present on one
+   and absent on the other is conclusive; a raw list of grants for the broken field alone is not,
+   because you have no baseline for what "granted" looks like on that record.
+
+> **⚠ Before spending any time on steps 1–3, check whether ACL can even be the cause.** If the
+> field is **`_`-prefixed and requested through an explicit `fields=` list**, `AclFieldPermissions`
+> is **bypassed entirely** and no grant you add or remove will change the result — see
+> [V2 REST query contract → ACL behavior](../../api2/features/v2-rest-query-contract.md). Confirm
+> the request shape first; it eliminates the entire ACL chain in one step.
+
 **Role ids differ per client DB**, so never hardcode a `roleId` in a `CLIENT` ACL migration —
 resolve it with a subselect, e.g. the Base role:
 
@@ -423,6 +489,46 @@ and **succeeds with 0 inserted and no error**. Always confirm the sibling has ro
 `shippingMethodId` (338), `measures.slug` (723), `containsBattery` (962), `shipToAddressId` (991).
 **Do NOT mirror `needsReturnLabel`** — its grants are absent in some clients.
 
+### ⚠ But when you know the TARGET role, grant it EXPLICITLY — mirroring is the riskier option
+
+The mirror practice above answers *"which roles read this kind of field?"* when you genuinely do not
+know. **When you already know the role you need, name it — do not mirror.** Mirroring looks tidier
+and reads as the house style (`Client/2026-07-22c` is the precedent), but it copies whatever the
+sibling happens to have in each tenant, and that set is **not uniform**. Two live failures from one
+2026-09-01 survey of the `PurchaseOrderItems._qty*` fields:
+
+- **Mirroring over-grants.** `Client_Compass` grants `quantity` to **role 4 (Public)**. A migration
+  mirroring `quantity` would have handed the **Public** role read access to eight derived inventory
+  quantities across that tenant — a real widening, applied silently, in a file whose stated purpose
+  was to grant the API role.
+- **Mirroring under-grants.** `Client_Imhouston` has **no `quantity` grant at all**, so the same
+  mirror inserts **zero rows** there and the field stays broken — the silent-no-op failure already
+  described above.
+
+**Rule: resolve the role BY NAME (`(SELECT id FROM Roles WHERE name = 'API')`) and grant it
+explicitly.** You keep the per-tenant role-id independence that mirroring was bought for, without
+inheriting a per-tenant role *set* you never inspected. Reserve mirroring for the case where the
+reader role is genuinely unknown — and when you do mirror, dry-run it per tenant and read the role
+ids it would actually insert.
+
+### Fleet reality check: a template mis-seed means "most tenants" is not "correct"
+
+The same survey (36 production client databases, 2026-09-01) on the eight
+`PurchaseOrderItems._qty*` fields:
+
+| Grant state | Tenants |
+|---|---|
+| all eight granted to **role 1 (Base)**, **none to role 3 (API)** | **31** |
+| **no `_qty*` grants at all** | 4 — Compass, Imhouston, Mcgrawhill, Tdsynnex |
+| roles 1 **and** 3 (correct) | 1 — Prudential |
+| role 3 (correct for API use) | 1 — Northwell |
+
+**A 31-of-36 majority was the WRONG state**, not the baseline — this is a template-level mis-seed
+propagated by the blank-client DDL, so every tenant provisioned from it inherits the same gap.
+Practical consequence: **never infer the intended grant from what most tenants have.** Derive it
+from which role actually reads the field, then check whether the majority agrees; when it does not,
+suspect the template rather than the two outliers.
+
 Reconfirmed 2026-08-03 (TRUE-80494): `measures.measureType` had **zero** grant rows in dev-sandbox
 `Client_Growrk`, so it was omitted from `GET /v2/measures`; the frontend's strict
 `m.measureType === "LENGTH"` split then produced empty arrays and **both unit dropdowns rendered
@@ -492,6 +598,26 @@ hardcoded `Core.RecordFields` id literals instead of a subselect.
       and every repo is on the **same branch** so the generated model matches the DB.
 
 ## Change history
+- **2026-09-01** — Four additions from a `PurchaseOrderItems._qty*` grant investigation.
+  (1) **Read `Core.Records.aclDatabase` FIRST** — both databases carry an `AclFieldPermissions`
+  table, so checking Core for a `CLIENT`-acl record (here `purchase-order-items`, record 18) returns
+  rows and a confident wrong answer; added the compare-a-working-field diagnostic recipe, gated on
+  first confirming ACL can even apply (an `_`-prefixed field in an explicit `fields=` list **bypasses
+  `AclFieldPermissions` entirely** — new section in
+  [v2-rest-query-contract](../../api2/features/v2-rest-query-contract.md)).
+  (2) **Grant a KNOWN target role explicitly rather than mirroring a sibling** — mirroring `quantity`
+  would have granted **role 4 (Public)** eight derived inventory quantities on `Client_Compass` and
+  inserted **nothing** on `Client_Imhouston` (no `quantity` grant there); resolve by role *name*
+  instead. This qualifies, and partly reverses, the house mirror precedent `Client/2026-07-22c`.
+  (3) **A 31-of-36 majority can be the wrong state** — 31 prod tenants grant the `_qty*` fields to
+  role 1 and none to role 3; only Prudential and Northwell are correct. Template-level mis-seed, so
+  never infer the intended grant from the majority.
+  (4) **Expanded the known-broken cross-cluster file list from 2 to 12** (full `dbchanges2` sweep;
+  all `Client/` ACL/surface grants in a 2026-06-25 → 2026-07-23 window, `Core/` clean), stated the
+  silent failure mechanism (`SET @x = (SELECT … FROM Core.X)` → NULL → guard suppresses the INSERT →
+  reports success), confirmed `Client_Adyen` as a live instance, verified on prod that the client
+  cluster hosts no `Core` at all, and noted the new `dbchanges2-cluster-isolation` PreToolUse hook
+  blocks new ones while these 12 remain a remediation backlog. (apeterson)
 - **2026-08-29** — Two more worked examples of the **standard-field write grant via hardcoded
   `Core.RecordFields` id literal** (the cross-cluster caveat — a `Client_*`→`Core` JOIN is refused on the
   prod client cluster), each cloning a working sibling: `ItemReceipts.transferOrderId` (Core RF **2153**,

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-08-30
+updated: 2026-09-01
 owners: [tcox, bala, apeterson, jcardinal]
 files:
   - api2/Component/Api/V2/V2.php
@@ -259,6 +259,46 @@ where=(field:op:value,LOGIC,field:op:value,(nested,OR,nested))
     list, **and the permitted data still populated**.
   - **Recommendation: always send an explicit `fields=` list.** Silent omission is how a
     consumer ends up "working" against data it never actually received.
+  - **⚠ That recommendation holds for PLAIN fields only — an `_`-prefixed field named in
+    `fields=` is never ACL-checked at all.** See the next section.
+
+### ⚠ An explicitly-requested `_`-prefixed field BYPASSES `AclFieldPermissions` entirely
+
+This is the exception to everything above, and it inverts the usual debugging instinct: for an
+underscore-prefixed field, **adding an `AclFieldPermissions` grant changes nothing** about an
+explicit `fields=` request. Verified 2026-09-01 on `purchase-order-items._qty*`.
+
+`processRoutePairs()` classifies each entry of an explicit `fields=` list in a fixed order, and the
+ACL branch is **not first**:
+
+| `V2.php` | branch | ACL checked? |
+|---|---|---|
+| **:3338** | `$modelFieldConfig[$f]['type'] == _Model::FIELD_SQL` → **calculated field** | **no** |
+| **:3353** | field starts with `_` but is not `FIELD_SQL` → reclassified as an **aggregate function** (`'function' => substr($field, 1)`) | **no** |
+| **:3375–3381** | plain field with no grant → *"not permitted access, unauthorized"* → **`EZ-2`** | yes |
+
+So `fields=_qtyAvailable` resolves at **:3338** and the request never reaches the ACL branch. The
+ACL gate for calculated fields lives at **:7216** in `getFullModelData()` — which is the
+**no-explicit-`fields=`** path only.
+
+**The two practical consequences:**
+
+1. **Granting `AclFieldPermissions` does not change the result of an explicit `fields=` request for
+   a calculated field.** If a `_qty*` field returns `0` with the grant added and with it removed,
+   the ACL was never the variable — stop testing grants and go look at the SQL the field emits
+   (and at *which model class* is emitting it — see the NYCHH case linked below).
+   The grant is still worth having: it is load-bearing on the `getFullModelData()` path.
+2. **Plain fields fail LOUDLY, calculated fields fail SILENTLY.** An ungranted plain field is a
+   `EZ-2` 403 you cannot miss. An ungranted `_`-prefixed field is quietly turned into an aggregate
+   function, and — because these fields typically carry
+   `FIELDOPT_SQL_TYPE => FIELD_DECIMAL` — the serializer still emits the key and it renders as
+   **`0`**. It reads as a broken calculation, not as a permission problem, which is exactly the
+   wrong place to start looking. (The `FIELD_DECIMAL` cast is documented on
+   [FIELD_SQL calculated fields](../../_underscore/features/calculated-sql-fields.md).)
+
+**Corollary for the `fields=`-forces-`EZ-2` diagnostic above:** re-requesting with an explicit
+`fields=` list to smoke out a denied field **only works on plain columns**. It will never produce an
+`EZ-2` for a `_`-prefixed field, so a silent `0` is not evidence that the grant exists.
 - **`EZ-1` vs `EZ-2` for a consumer:** `EZ-1` = record-level block (`data.<route>` is `null`) —
   hard blocked, nothing usable. `EZ-2` = field-level — on a **LIST** it is
   *degraded-but-usable*; on a **by-uuid READ** it is **fatal**.
@@ -296,7 +336,14 @@ where=(field:op:value,LOGIC,field:op:value,(nested,OR,nested))
 - **A 500 (`EO-1`) on a filter ⇒ suspect a `where` reference to an unjoined table.**
 - **`gte`/`lte` silently are not operators** — use `ge`/`le`.
 - **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.
+  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
+  `EZ-2` (see the ACL section).
+- **⚠ A calculated field returning `0` is almost never an ACL problem.** Eliminate ACL in one
+  step (it is bypassed on the explicit-`fields=` path), then check **which model class** supplies
+  the expression — a `_Model_<Client>_X` override on the *deployed* `_underscore` branch can
+  replace the base SQL with something that legitimately evaluates to `0`. Worked example:
+  [NYCHH transfer-order inventory quantities](../../../clients/nychh/features/transfer-order-inventory-quantities.md).
 - **⚠ A PUT response ECHO can omit a field that DID persist — verify against the DB, not the echo.**
   A `PUT /v2/inventory-adjustments/{uuid}` with `{"itemFulfillment":{"uuid":…}}` returned **200 with
   an empty `messages[]`** and an echo that did **not** contain `itemFulfillment`, yet the FK column
@@ -306,6 +353,16 @@ where=(field:op:value,LOGIC,field:op:value,(nested,OR,nested))
   [V2 request logging](request-logging.md).
 
 ## Change history
+- 2026-09-01 — **Recorded the biggest exception to this doc's own "always send an explicit `fields=`
+  list" advice: an `_`-prefixed field named in `fields=` is NEVER ACL-checked.** `V2.php:3338`
+  classifies a `FIELD_SQL` field as calculated *before* the ACL branch at `:3353`, and `:3353` then
+  reclassifies any other `_`-prefixed field as an **aggregate function** rather than denying it —
+  only plain fields reach the `EZ-2` branch at `:3375-3381`. The ACL gate for calculated fields is
+  at `:7216`, on the **no-explicit-`fields=`** path. Two consequences: adding an
+  `AclFieldPermissions` grant cannot change the result of an explicit `fields=_qtyX` request, and
+  ungranted calculated fields fail **silently as `0`** (the `FIELDOPT_SQL_TYPE => FIELD_DECIMAL`
+  cast still emits the key) while plain fields fail loudly. Found while a `_qty*` field returned 0
+  and a grant migration was written against the wrong theory. (apeterson)
 - 2026-08-29 — Recorded two response-shape facts from the NYCHH inventory-adjustment REST work: **a
   non-null FK object one hop past the max `depth` is silently omitted** (a null sibling FK still
   renders, so it reads as "null" not "missing") — `GET /item-fulfillment-items` at `depth:2` dropped

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

@@ -3,7 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Database Changes (dbchanges2) Repository Architecture](architecture.md) | `dbchanges2` is the **schema-migration / SQL change-set repository** for the entire 2.0 platform. | Core/, Client/, Client_<Tenant>/, Logs/, Logs_Client/, _modules/ |
-| [Re-runnable additive migrations (uuid4 in SQL, INSERT guards, the DISTINCT trap, conditional ALTERs)](features/rerunnable-additive-inserts.md) | Most `dbchanges2` files are **additive data grants** run by hand against production, often more than once (once per environment, or twice because someone was no | dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql, dbchanges2/Core/2026-08-27a - Insert - Netsuite Location SyncAll CronJob.sql |
+| [Re-runnable additive migrations (uuid4 in SQL, INSERT guards, the DISTINCT trap, conditional ALTERs)](features/rerunnable-additive-inserts.md) | Most `dbchanges2` files are **additive data grants** run by hand against production, often more than once (once per environment, or twice because someone was no | dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql, dbchanges2/Core/2026-08-27a - Insert - Netsuite Location SyncAll CronJob.sql, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql |
 | [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Core/2026-08-31a - SalesOrderDenialDetailsSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-31a - SalesOrderDenialDetailsReadOnlyRules.sql, toga25-supply/db-migrations/PLAYBOOK.md, toga25-supply/db-migrations/SURFACE-FEATURE-RUNBOOK.md, dbchanges2/Client_Compass/, dbchanges2/Client_CompassCanada/, dbchanges2/Client_Quad/, dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql, dbchanges2/Core/2026-08-24b - SalesOrderStatusFilterSurfaceSeed.sql, dbchanges2/Client_Compass/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_CompassCanada/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Quad/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Client_Nychh/2026-08-24b - SalesOrderStatusFilterHides.sql, dbchanges2/Core/2026-08-21 - SalesOrderDecisionSurfacesReseed.sql, dbchanges2/Core/2026-08-24 - RestoreApproveDenyRowActionsVisibility.sql, dbchanges2/Client_Quad/2026-08-24 - ProdPortApprovePoNumberEnabledRule.sql, dbchanges2/Client_Quad/2026-07-21b - ApproveDisabledTooltipPoNumber.sql, dbchanges2/Client_Quad/2026-08-21 - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_CompassCanada/2026-08-24 - ProdPortApprovalsGateAndApproveStepTwoRule.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Core/2026-07-20a - Update - HideAdminNotesSectionByDefault.sql, dbchanges2/Core/2026-07-20b - Update - NotesSectionFieldElements.sql, dbchanges2/Client_Compass/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_Compass/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_Quad/2026-07-20a - NotesSectionFieldsOverride.sql, dbchanges2/Core/2026-07-20c - Update - VendorItemsToggleSurfaceSeed.sql, dbchanges2/Client_Compass/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Core/2026-07-20e - RestoreApproveDenyRowActions.sql, dbchanges2/Client_Compass/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20e - RowActionsApprovalWorkflowAdminEnable.sql, dbchanges2/Core/2026-07-17 - README - RUN ORDER.md, dbchanges2/Client_Compass/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Compass/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_CompassCanada/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_CompassCanada/2026-07-21b - SalesOrderApprovalsGateEnable.sql, dbchanges2/Client_Quad/2026-07-21a - SalesOrderApproveEnabledRuleOverride.sql, dbchanges2/Client_Quad/2026-07-21b - SalesOrderApproveDisabledTooltipTranslation.sql, dbchanges2/Core/2026-07-21a - SalesOrderDecisionSummarySurfaceSeed.sql, dbchanges2/Core/2026-07-21b - SalesOrderDecisionActionSurfaceSeed.sql, dbchanges2/Client_Quad/2026-07-21c - SalesOrderDecisionSummaryOverride.sql, dbchanges2/Client_Compass/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Client_CompassCanada/2026-07-21c - SalesOrderDecisionSummaryTotalConcat.sql, dbchanges2/Core/2026-07-23a - PoNumberDetailFieldValueKey.sql, dbchanges2/Core/2026-07-29a - SalesOrderApprovalDetailsSurfaceSeed.sql, dbchanges2/Core/2026-08-05b - ApprovalDetailsShippingMethodConcatCharge.sql, dbchanges2/Core/2026-08-14a - NoteBadgesVocabularySurface.sql, dbchanges2/Client/2026-08-14a - NoteBadgeThemeTokens.sql, dbchanges2/Client/2026-08-14b - NoteBadgeUserColorFix.sql, dbchanges2/Client_Compass/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Client_CompassCanada/2026-08-14a - NoteBadgeDelegateThemeTokens.sql, dbchanges2/Core/2026-08-26a - ServiceRequestRecordHeaderSurfaceSeed.sql, dbchanges2/Core/2026-08-26b - ServiceRequestDetailsSurfaceSeed.sql, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql |
 | [2.0 New-Client Onboarding (manual process)](workflows/client-onboarding.md) | > **A local browser wizard now automates this.** Steps 2–9 below (create DBs, generate Core/API > inserts, append to `Clients_Db.txt`) — plus the dbchanges2 bla | Client/, Client_<Tenant>/, Core/, Logs_Client/ |
 | [Auditing a client DB that drifted from its models (partially applied module migration)](workflows/client-schema-drift-audit.md) | A recurring 2.0 failure mode: **one client's database drifts from what the PHP models declare**, usually because a `_modules/<module>/` migration was applied to | dbchanges2/Client_Growrk/2026-05-28.sql, dbchanges2/Client_Growrk/2026-08-10c - GrowrkServiceRequestCustomFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10d - GrowrkServiceRequestTypeAndDispositionSeeds.sql, dbchanges2/_modules/netsuite/2026-07-10a - UnitInventoryFields.sql, dbchanges2/Client_Growrk/2026-08-10 - GrowrkUnitInventoryFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10b - GrowrkUnitItemDescriptionAcl.sql, dbchanges2/Client_Growrk/_modules.txt |

package/knowledge/2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md

@@ -6,15 +6,17 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-08-31
+updated: 2026-09-01
 owners: [bala, kyalamarthi, apeterson]
 files:
   - dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql
   - dbchanges2/Core/2026-08-27a - Insert - Netsuite Location SyncAll CronJob.sql
+  - dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql
 related:
   - ../architecture.md
   - ../../worker2/features/netsuite-salesorder-open-orders-sync.md
   - ../../_underscore/features/acl-permission-chain.md
+  - ../../_underscore/features/calculated-sql-fields.md
   - ../../_underscore/features/tracking-number-bridges.md
   - ../../../../clients/compass-usa/workflows/granting-persona-bundle-access.md
   - ../../../../clients/compass-usa/workflows/granting-navigation-access.md
@@ -49,6 +51,36 @@ and `SUBSTRING('89ab', …)` picks the variant nibble. Verified working on prod
 that is *not* v4-shaped (older migrations concatenated `RANDOM_BYTES` without the version/variant
 nibbles). They are fine and must not be "fixed" — but do not use them as the template for new SQL.
 
+### ⚠ In a FAN-OUT grant migration, use HARDCODED uuid literals — generated uuids make rollback unsafe
+
+The generator above is right for a normal additive insert. It is **wrong for a `Client/` fan-out
+that grants a permission across every tenant**, because you cannot write a safe rollback for rows
+whose uuids you do not know.
+
+The tempting rollback is a natural key:
+
+```sql
+-- DANGEROUS in a fan-out: deletes grants this file never created
+DELETE FROM AclFieldPermissions WHERE recordFieldId IN (…) AND roleId = (SELECT id FROM Roles WHERE name = 'API');
+```
+
+That also removes **pre-existing** grants held by the tenants that were already correct. Concrete
+case (2026-09-01, the `PurchaseOrderItems._qty*` role-3 grant): Prudential and Northwell already had
+these rows, so a key-based rollback would have **revoked working production permissions** on two
+tenants as collateral for undoing 34 others.
+
+**Instead, hardcode one v4 uuid literal per row in the file.** The rollback is then exact:
+
+```sql
+DELETE FROM AclFieldPermissions WHERE uuid IN ('<literal-1>', …, '<literal-8>');
+```
+
+It can only ever match rows this file inserted. **Reusing the same literal across tenants is valid**
+— `uuid` is unique *per table per database*, and each tenant is a separate database, so one literal
+per (row × file) is enough for the whole fan-out. Keep the `NOT EXISTS` guard on the real unique key
+(here `(recordFieldId, roleId)`) so re-running is still a no-op on tenants that already have the
+grant; the literal governs only deletion.
+
 ### ⚠ `DISTINCT` cannot dedupe a row that carries a random uuid
 
 This is the silent one. In an `INSERT … SELECT`, putting the uuid expression inside a
@@ -235,8 +267,29 @@ concluding a migration is production-safe.
   file: separate production clusters mean a `Core.` reference is unrunnable in prod even though it
   works locally. Hardcode `Core.Records` / `Core.RecordFields` ids as literals — see
   [dbchanges2 architecture](../architecture.md).
+- **⚠ Read the sibling migration's `INSERT` HEADER — never infer the column list from its `VALUES`
+  row.** Copying a neighbouring file is the normal way to start a migration, and matching the
+  *shape* of its values tuple (right arity, plausible-looking types) produces a file that looks
+  correct and fails on execution. Verified 2026-09-01: `Core.Messages` is
+  **`(id, uuid, dtCreated, messageKey, name, defaultValue)`** — a guess of `slug` / `message`
+  (inferred from a sibling's values row) died on `Unknown column 'slug'`. When in doubt,
+  `SHOW COLUMNS FROM <Table>` costs one round-trip.
+- **`Core.RecordFields` has NO `sql` column.** A calculated field's SQL is **not** stored in
+  metadata — it lives in the `_underscore` model as a `FIELD_SQL` static method. Do not go looking
+  for a migration to change a calculated field's expression; there is none. See
+  [FIELD_SQL calculated fields](../../_underscore/features/calculated-sql-fields.md).
 
 ## Change history
+- 2026-09-01 — Added the **fan-out rollback rule**: a `Client/` grant migration that fans out across
+  every tenant must use **hardcoded v4 uuid literals**, not the generator, so its rollback
+  (`DELETE … WHERE uuid IN (…)`) can only touch rows that file created. A natural-key rollback on
+  `(recordFieldId, roleId)` would have revoked **pre-existing production grants** on Prudential and
+  Northwell while undoing the `PurchaseOrderItems._qty*` role-3 fan-out. Reusing one literal per row
+  across tenants is valid (uuid is unique per table per database). Also recorded two schema gotchas:
+  **read a sibling's `INSERT` header, never infer columns from its `VALUES` row** (`Core.Messages` is
+  `(id, uuid, dtCreated, messageKey, name, defaultValue)` — a guessed `slug` failed with *Unknown
+  column*), and **`Core.RecordFields` has no `sql` column** — calculated-field SQL lives in the
+  model, not in metadata. (apeterson)
 - 2026-08-28 — Added **conditional (re-runnable) ALTERs**: MySQL 8 has no
   `ADD COLUMN IF NOT EXISTS`, so a `Client/` all-tenant file must gate each `ALTER` on
   `information_schema` (with `TABLE_SCHEMA = DATABASE()` for cluster safety) and run it through

package/knowledge/2.0/apps/dbchanges2/workflows/targeting-the-right-database.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: workflow
 status: active
-updated: 2026-08-31
+updated: 2026-09-01
 owners: [apeterson]
 files:
   - api2/Config/production.ini
@@ -85,11 +85,24 @@ Delete the file when you are done.
   `Table 'Client_Nychh.Messages' doesn't exist`, which names a missing table rather than the real
   mistake. If you see "table doesn't exist" for a table you know is in Core, check which schema you
   piped the file into before you touch the SQL.
+- 🚨 **A `Client/` fan-out hits EVERY `Client_*` schema on the cluster — including dated BACKUP
+  databases.** The production client cluster carries copies that are not tenants. Found
+  2026-09-01: **`Client_Compass_20260831_120000`**, a dated backup of `Client_Compass`, sitting
+  alongside the live schemas. Any "run this against every `Client_*` database" loop picks it up,
+  which at best wastes a run and at worst mutates a snapshot someone is holding for a restore.
+  **Before a fan-out, list the target schemas and eyeball them** —
+  `SHOW DATABASES LIKE 'Client\_%'` — and exclude anything matching a `_YYYYMMDD_HHMMSS` suffix or
+  otherwise absent from `Core.Clients`. Do not assume the tenant list and the schema list agree.
 - **The repo is evidence of intent, never of what an environment contains.** Confirming a file ran
   is its own procedure — see
   [Verifying whether a migration actually ran](./verifying-a-migration-ran.md).
 
 ## Change history
+- 2026-09-01 — Added the **backup-database hazard for `Client/` fan-outs**: the production client
+  cluster hosts dated snapshots alongside live tenants (`Client_Compass_20260831_120000`, found
+  during a 36-database ACL survey), and a naive "every `Client_*` schema" loop will run against
+  them. List and filter the target schemas (`SHOW DATABASES LIKE 'Client\_%'`, drop
+  `_YYYYMMDD_HHMMSS` suffixes / anything not in `Core.Clients`) before fanning out. (apeterson)
 - 2026-08-31 — Initial. Captured after a dump taken from `127.0.0.1` was restored onto sandbox-client
   `Client_Nychh` believing it was production (the tell: sandbox matched local exactly). Records the
   verify-by-differing-row-count check, the `--single-transaction` snapshot-drift caveat, the

package/knowledge/2.0/apps/toga-blox/features/api-client.md

@@ -6,7 +6,7 @@ project: TOGa Blox
 client: shared
 type: feature
 status: active
-updated: 2026-08-27
+updated: 2026-09-01
 owners: [apeterson, tcox]
 files:
   - toga-blox/src/reactQuery/queryHelpers.ts
@@ -118,6 +118,25 @@ Filterable`, `hyperlinkField`, `imageUrlField`, `sticky`, `precision`, …), `Da
   paren pair so the group re-wrap doesn't double-wrap. Any raw pre-formatted where clause was
   100% broken before this. If you add a new raw-string clause path, route it through this string
   branch — do **not** feed a raw clause into an object-expecting serializer.
+- **⚠ Every `where` VALUE must be a STRING — a number throws inside `buildUrl` and NO request is
+  ever sent.** `urlEncode(input: string)` calls `input.replace()`, so a numeric value raises
+  `input.replace is not a function` **synchronously** inside `assembleOptions` → `buildUrl` →
+  `queryFn`. React Query reports it as a query error, and because the throw happens *before* the
+  fetch, **DevTools shows no network activity at all** — the symptom is an empty list/dropdown with
+  a completely clean network tab, which reads as a backend or ACL problem and is neither.
+
+  ```ts
+  // WRONG — throws in buildUrl, no HTTP request
+  where: { "Locations.isActive": { "=": 1 } }
+
+  // CORRECT
+  where: { "Locations.isActive": { "=": "1" } }
+  ```
+
+  TypeScript does not catch it today. This is the **second** shape-assumption failure in
+  `reactQuery/queryHelpers.ts` (the raw-string `apiWhereClause` bug above is the first): the
+  serializer trusts its input's type and fails loudly only at the very end of the chain. Verified
+  2026-09-01 in `toga25-supply` (`useTargetLocationOptions.ts`, `useTransferSourceLocation.ts`).
 - **⚠ AUTHORING DEFECT — `handleClientAuthentication(uuid)` collides by name with app-local SSO
   helpers and is not interchangeable with them.** blox's version `POST`s
   `/auth/encrypted-user-uuid` with an **empty payload** (`{client:"",user:""}`), writes
@@ -152,6 +171,12 @@ Filterable`, `hyperlinkField`, `imageUrlField`, `sticky`, `precision`, …), `Da
   thread, not a settled finding.
 
 ## Change history
+- 2026-09-01 — Recorded that **`where` values must be STRINGS**: `urlEncode` calls
+  `input.replace()`, so a numeric value throws `input.replace is not a function` synchronously in
+  `buildUrl`/`queryFn` and **no HTTP request is made at all** — an empty dropdown with a clean
+  network tab, easily misread as a backend/ACL fault. Second shape-assumption failure in
+  `reactQuery/queryHelpers.ts` after the 2026-08-17 raw-string clause bug; TypeScript does not catch
+  it. Hit in `toga25-supply`'s Create Transfer Order modal. (apeterson)
 - 2026-08-27 — Recorded three blox **authoring defects** surfaced while debugging toga25-supply SSO:
   (1) `handleClientAuthentication` collides by name with app-local SSO helpers and returns a
   `/users` payload with no `singleSignOnServiceUrl`; (2) `fetchPublicToken` persists the public

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

@@ -14,7 +14,7 @@
 | [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. | toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/src/routes.tsx, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/api/api.ts |
 | [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 | toga25-supply/src/App.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/DenialBanner.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/SalesOrderRecordModal.module.css, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/SalesOrderApprovalModalsLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/RecordApprovalModalLayout.tsx, toga25-supply/src/layout/RecordApprovalModal/view/ApprovalTimelineView.tsx, toga25-supply/src/layout/RecordApprovalModal/ApprovalModal.module.css, toga25-supply/src/utils/formatDateTime.ts, toga25-supply/src/utils/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/layout/RecordApprovalModal/, toga25-supply/src/contexts/AuthContext.tsx, toga25-supply/src/surface/applyColSpan.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx, toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/ServiceRequestRecordModalLayout.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/view/ServiceRequestsView.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/useServiceRequestRecordModalLayoutModel.tsx, toga25-supply/src/pages/ServiceRequests/view/ServiceRequestRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/AdminNotesSection.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getAdminNotes.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SurfaceRowActions.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderVip.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/surface/SurfaceHeader.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
 | [Talos Integration (AppLayout host + adapter wiring)](features/talos-integration.md) | toga25-supply is the first host of the shared blox [Talos assistant](../../toga-blox/features/talos-assistant.md). | toga25-supply/src/layout/AppLayout/AppLayout.tsx, toga25-supply/src/components/Header/Header.tsx, toga25-supply/src/components/Header/Header.module.css, toga25-supply/src/index.css, toga25-supply/src/assets/talos-owl.png |
-| [Transfer Orders page (TableView → Core surfaces → React page + record modal)](features/transfer-orders-page.md) | The Transfer Orders screen — list + read-only record modal — built end to end on 2026-08-28 from a Claude Design prototype. | toga25-supply/src/pages/TransferOrders/TransferOrders.tsx, toga25-supply/src/pages/TransferOrders/hooks/useTransferOrdersTableState.ts, toga25-supply/src/pages/TransferOrders/viewModel/useTransferOrdersPageViewModel.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrdersTableLayout/TransferOrdersTableLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/TransferOrderRecordModalLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/hooks/useTransferOrderRecord.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/viewModel/useTransferOrderRecordModalLayoutModel.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/view/TransferOrderRecordView.tsx, 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/useTransferableItemRows.ts, toga25-supply/src/surface/useColumnVisibilityModalConfig.ts, toga25-supply/src/routes.tsx, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql |
+| [Transfer Orders page (TableView → Core surfaces → React page + record modal)](features/transfer-orders-page.md) | The Transfer Orders screen — list + read-only record modal — built end to end on 2026-08-28 from a Claude Design prototype. | toga25-supply/src/pages/TransferOrders/TransferOrders.tsx, toga25-supply/src/pages/TransferOrders/hooks/useTransferOrdersTableState.ts, toga25-supply/src/pages/TransferOrders/viewModel/useTransferOrdersPageViewModel.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrdersTableLayout/TransferOrdersTableLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/TransferOrderRecordModalLayout.tsx, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/hooks/useTransferOrderRecord.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/viewModel/useTransferOrderRecordModalLayoutModel.ts, toga25-supply/src/pages/TransferOrders/view/TransferOrderRecordModalLayout/view/TransferOrderRecordView.tsx, 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/useTargetLocationOptions.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useTransferSourceLocation.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useLocationContacts.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/hooks/useCreateLocationContact.ts, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/AddContactModal.tsx, toga25-supply/src/pages/TransferOrders/view/CreateTransferOrderModal/view/TransferNotesField.tsx, dbchanges2/Client/2026-09-01a - PurchaseOrderItemQtyFieldsApiRoleRead.sql, toga25-supply/src/surface/useColumnVisibilityModalConfig.ts, toga25-supply/src/routes.tsx, dbchanges2/Core/2026-08-28a - TransferOrderSurfaceSeed.sql, dbchanges2/Core/2026-08-28b - TransferOrderListActionsSurfaceSeed.sql, dbchanges2/Client/2026-08-28a - TransferOrderStageThemeTokens.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql |
 | [AWS Amplify Multi-Environment Deployment](workflows/amplify-deployment.md) | How `toga25-supply` deploys to **all** of its environments on AWS Amplify from a **single shared `amplify.yml`**. | toga25-supply/amplify.yml, toga25-supply/src/api/api.ts, toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/vite.config.ts, toga25-supply/package.json, toga25-supply/.env.development |
 | [Cypress Testing Harness (component + e2e)](workflows/cypress-testing.md) | The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch (`cypress` was already a dependency but there was no config, no `cypress/` | toga25-supply/cypress.config.ts, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/fixtures.ts, toga25-supply/cypress/support/mocks/useApprovalModalViewModel.ts, toga25-supply/cypress/component/SalesOrderApprovalModalsLayout.cy.tsx, toga25-supply/cypress/component/RecordApprovalModalLayout.cy.tsx, toga25-supply/cypress/component/EnterPoNumberModal.cy.tsx, toga25-supply/cypress/e2e/salesOrderApproval.cy.ts |
 | [Porting a page (or query) from toga2-supply to toga25-supply](workflows/porting-a-page-from-toga2-supply.md) | `toga25-supply` re-implements pages that already exist in `toga2-supply`. | toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/PRUDENTIAL/exportApiFields.json, toga25-supply/src/pages/SalesOrders/api/prudentialExportApi.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, toga2-supply/src/components/ui/Tables/hooks/useExportableData.tsx |

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

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: architecture
 status: active
-updated: 2026-06-23
+updated: 2026-09-01
 owners: [apeterson]
 files:
   - toga25-supply/src/main.tsx
@@ -111,5 +111,12 @@ its primary consumer and resolves it via a symlinked `node_modules/@agilant/toga
   each other's cached data (e.g. record modal vs. approval modal — `scope="record-modal"` vs
   `scope="approval-modal"`). Including `additionalData` in the query key is mandatory for
   WHERE-filtered modal tables, or React Query serves a stale unfiltered first render.
+- **⚠ Data hooks must use `staleTime: 0` — the query cache is PERSISTED.** `App.tsx` wraps the app
+  in `PersistQueryClientProvider` with a `createSyncStoragePersister` on the `localStorage` key
+  `supply-chain-query-cache`, so cache entries survive reloads *and* sessions. The `QueryClient`
+  default is `staleTime: 0` for exactly this reason. A hook that sets its own non-zero `staleTime`
+  can serve a persisted entry from a **previous session** and never fetch — the symptom is an empty
+  list/dropdown with **nothing in the network tab**, which reads as a backend fault and is not one.
+  (`staleTime: Infinity` on the **surface-meta** hooks is a deliberate, separate exception.)
 - **Typecheck with `npx tsc --noEmit` / `npx tsc -b`** after changes; adding a required key to
   `ClientFields` surfaces every bundle missing it.