toga-ai 1.0.835 → 1.0.837

package/knowledge/1.0/apps/tools/INDEX.md

@@ -17,6 +17,6 @@
 | [Tools Persona-Gated Navigation (App_Nav)](features/persona-gated-navigation.md) | `App_Nav` is the Tools app's two-level, **persona-gated** navigation. |
 | [Tools SAML SSO Consumer & Persona-Gated Auth (App_Auth)](features/saml-sso-auth.md) | `App_Auth` is the Tools app's authentication layer: it consumes the SAML gateway `?saml=` handoff (see the 2.0 SAML downstream integration contract), establishe |
 | [Talos Knowledge Base Admin UI (KB Documents + Vocabulary)](features/talos-kb-documents-admin.md) | > **PER-AI-MODEL, DATA-DRIVEN SCOPING (2026-07-29).** The KB-documents and Vocabulary admin > UIs were refactored from a single hard-coded **"development-team"* |
-| [Talos Pricing UI (Contracts, Pricing Dashboard, Usage, Settings + Estimator)](features/talos-pricing-ui.md) | The 1.0 (tools app) face of the **Talos Pricing Platform** — a "Talos Pricing" nav folder with four pages plus the estimate engine. |
+| [Talos Pricing UI (Contracts, Pricing Dashboard, Usage, Settings + Estimator)](features/talos-pricing-ui.md) | The 1.0 (tools) face of the Talos Pricing Platform — Contracts / Pricing Dashboard / Usage / Pricing Settings pages + the estimate engine, reading the Team DB v |
 | [App-Wide Colour Theme (light / dark / auto)](features/theme-light-dark.md) | A **light / dark / auto** colour theme for the *entire* Tools app, built as a single semantic-token layer (`assets/css/theme.css`) rather than per-page edits. |
 | [Deploying Tools to Elastic Beanstalk (PHP 8.5 / Amazon Linux 2023)](workflows/deploy-to-elastic-beanstalk-al2023.md) | How the **Tools** 1.0 app boots on Elastic Beanstalk running `PHP 8.5 on 64bit Amazon Linux 2023/4.13.1 (aarch64)`. |

package/knowledge/1.0/apps/tools/features/talos-pricing-ui.md

@@ -6,11 +6,12 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-08-04
+updated: 2026-09-17
 owners: [jcardinal]
 files:
   - tools/_/app/nav.php
   - tools/_/app/talos/estimator.php
+  - tools/_/app/talos/estimator.parity.test.php
   - tools/_/app/talos/usage.php
   - tools/mvc/talos/contracts/get.php
   - tools/mvc/talos/contracts/post.php
@@ -29,100 +30,56 @@ related:
   - ../../../2.0/apps/worker2/features/talos-pricing-automation.md
 ---
 
+The 1.0 (tools) face of the Talos Pricing Platform — Contracts / Pricing Dashboard / Usage / Pricing Settings pages + the estimate engine, reading the Team DB via `db_team`; open for the contract lifecycle, worker-owned read-only rows, or the fetchOne/PHP 8.5 traps.
+
 ## Summary
 
-The 1.0 (tools app) face of the **Talos Pricing Platform** — a "Talos Pricing" nav folder
-with four pages plus the estimate engine. Restructured 2026-08-03 to
-**Contracts / Pricing Dashboard / Usage / Pricing Settings**. All pages read the **Team DB**
-through the `db_team` connection (`[database_team]` in `config.*.ini`).
+The 1.0 (tools app) face of the **Talos Pricing Platform** — a "Talos Pricing" nav folder with four pages plus the estimate engine. Restructured 2026-08-03 to **Contracts / Pricing Dashboard / Usage / Pricing Settings**. All pages read the **Team DB** through the `db_team` connection (`[database_team]` in `config.*.ini`).
 
 ## How it works
 
 ### Contracts (`mvc/talos/contracts/{get,post}.php`) — replaces `onboarding/*`
-The old Onboarding page could only **INSERT** (hardcoded `status='ONBOARDED'`, no edit, no
-delete), which is why nothing ever reached the tables. Contracts is a real lifecycle, reusing
-the existing status enum: **PROSPECT** = draft, **ACTIVE** = signed, **CHURNED** = ended.
-
-- **A signed contract can never be hard-deleted.** `TalosPricingBands` is
-  `ON DELETE CASCADE`, so deleting the client would destroy the agreed rate schedule and the
-  margin history with it. Signed contracts **churn**; they do not delete.
-- **Post-signature edits append to `TalosContractAmendments`** rather than mutating the
-  signed terms.
-- Includes an **Actual-vs-Estimate** comparison with variance chips, a month-by-month history
-  table plus cost/margin chart, and a one-click **"apply recommended org fee"**.
+The old Onboarding page could only **INSERT** (hardcoded `status='ONBOARDED'`, no edit, no delete), which is why nothing ever reached the tables. Contracts is a real lifecycle, reusing the existing status enum: **PROSPECT** = draft, **ACTIVE** = signed, **CHURNED** = ended.
+- **A signed contract can never be hard-deleted.** `TalosPricingBands` is `ON DELETE CASCADE`, so deleting the client would destroy the agreed rate schedule and the margin history with it. Signed contracts **churn**; they do not delete.
+- **Post-signature edits append to `TalosContractAmendments`** rather than mutating the signed terms.
+- Includes an **Actual-vs-Estimate** comparison with variance chips, a month-by-month history table plus cost/margin chart, and a one-click **"apply recommended org fee"**.
+- **Pricing model toggle + contract terms (2026-09-17).** The page now sets `pricingModel` (`PER_USER` / `PER_INTERACTION`), the fixed 1/3/5-year term dropdown (`contractTermMonths`), the per-interaction inputs (`contractedInteractionCount`, voice-only `avgMinutesPerInteraction`, `perInteractionFee`), and the two one-time contract fees (`implementationFee`, `trainingFee`). Model design, term ramp, fee amortization, and the recurring-vs-blended margin split are all in [pricing-cogs-model](../../../2.0/apps/talos/features/pricing-cogs-model.md) — not restated here.
 
 ### Pricing Dashboard (`pricing/get.php`) — rebuilt for sales leadership
-Portfolio KPIs, a 12-month blended-margin trend with the target band shaded, an exception
-list with deterministic explanations, and licensed-vs-active utilisation.
+Portfolio KPIs, a 12-month blended-margin trend with the target band shaded, an exception list with deterministic explanations, and licensed-vs-active utilisation.
 
 ### Usage (`usage/get.php`, `_/app/talos/usage.php`)
-Adds `costIntensity()` and a **Cost intensity** panel (tool-mix driven cost).
-
-**Fixed:** `clientOptions()` read `TalosClients WHERE status='ONBOARDED'` from an
-always-empty table, so the client selector rendered **empty**. It now calls
-`GET /api/usage/clients` with a Team-DB fallback.
+Adds `costIntensity()` and a **Cost intensity** panel (tool-mix driven cost). **Fixed:** `clientOptions()` read `TalosClients WHERE status='ONBOARDED'` from an always-empty table, so the client selector rendered **empty**. It now calls `GET /api/usage/clients` with a Team-DB fallback.
 
 ### Pricing Settings (`settings/{get,post}.php`) — replaces `factors/*`
-Technical-only (persona-narrowed on the action, per `mvc-data-access-patterns`). **Measured
-(derived) cost-factor rows are worker-owned and read-only**, enforced server-side with
-`UPDATE ... AND isDerived = 0`. Policy rows are editable and carry full-sentence labels.
+Technical-only (persona-narrowed on the action, per `mvc-data-access-patterns`). **Measured (derived) cost-factor rows are worker-owned and read-only**, enforced server-side with `UPDATE ... AND isDerived = 0`. Policy rows are editable and carry full-sentence labels.
 
 ### Removed
-- `mvc/talos/benchmarks/get.php` — read the never-populated `TalosUsageMonthly` and
-  duplicated a worse subset of the Usage page.
+- `mvc/talos/benchmarks/get.php` — read the never-populated `TalosUsageMonthly` and duplicated a worse subset of the Usage page.
 - `mvc/talos/onboarding/*` and `mvc/talos/factors/*` — superseded above.
 
 ### Estimator (`App_Talos_Estimator`, `_/app/talos/estimator.php`)
-Now driven by the **token unit price** and **workload profiles** instead of the feature
-checklist and per-client calibration factor (methodology in `pricing-cogs-model`). Service
-offering (CHAT / VOICE_TO_VOICE / NATURAL_VOICE) describes **modality only** and says nothing
-about cost; cost is driven by tool-call **intensity** via the profile
-(retrieval / general / analytics).
+Now driven by the **token unit price** and **workload profiles** instead of the feature checklist and per-client calibration factor (methodology in `pricing-cogs-model`). Service offering (CHAT / VOICE_TO_VOICE / NATURAL_VOICE) describes **modality only** and says nothing about cost; cost is driven by tool-call **intensity** via the profile (retrieval / general / analytics). Per-interaction model adds `costPerInteraction`, `estimateByInteraction`, `recommendedPricePerInteraction`, `recommendedOrgFeeInteraction`, `orgFeeOptionsInteraction`. Constants live in Team-DB `TalosCostFactors` (shared with worker2); a golden-master parity test (`estimator.parity.test.php` ↔ worker2 `PricingParityTest.php`, 11/11 pass) guards drift — see [pricing-cogs-model](../../../2.0/apps/talos/features/pricing-cogs-model.md).
 
 ## Gotchas
-
-- **`App_Database::fetchOne()` is not an existence test** — it 500s on zero rows. See
-  [mvc-data-access-patterns](./mvc-data-access-patterns.md); the original
-  `onboarding/post.php` carried this exact bug and would have fataled on the first save
-  anyone attempted, which is good evidence nobody ever completed an onboarding through it.
-- **This app runs PHP 8.5 and escalates deprecations to fatals** — `$arr[$row['nullableCol']]`
-  is fatal even inside `isset()`. Local dev on PHP 8.2 does **not** reproduce it. Cast to
-  `(string)` before indexing. See `mvc-data-access-patterns`.
-- **`.tool--wide` did nothing.** `assets/css/style.css` documented the class as escaping the
-  960px `.app-content` cap "via `:has()`", but that rule was never written. Added
-  `.app-content:has(.tool--wide) { max-width: 100% }` — which also makes the pre-existing
-  `mvc/errors` pages genuinely full-width for the first time.
-- **Put Talos page CSS in `style.css`, not a page-local `<style>` block.** The Contracts page
-  **returns early** for list mode, so a `<style>` block placed after that return applied to
-  the calculator only and the list rendered with no CSS at all.
-- **Voice multipliers (0.25 / 0.50) are UNVALIDATED** — supplied second-hand, never measured,
-  and possibly inverted. Flagged in the UI. **Do not quote voice from them.**
+- **`App_Database::fetchOne()` is not an existence test** — it 500s on zero rows. See [mvc-data-access-patterns](./mvc-data-access-patterns.md); the original `onboarding/post.php` carried this exact bug and would have fataled on the first save anyone attempted, which is good evidence nobody ever completed an onboarding through it.
+- **This app runs PHP 8.5 and escalates deprecations to fatals** — `$arr[$row['nullableCol']]` is fatal even inside `isset()`. Local dev on PHP 8.2 does **not** reproduce it. Cast to `(string)` before indexing. See `mvc-data-access-patterns`.
+- **`.tool--wide` did nothing.** `assets/css/style.css` documented the class as escaping the 960px `.app-content` cap "via `:has()`", but that rule was never written. Added `.app-content:has(.tool--wide) { max-width: 100% }` — which also makes the pre-existing `mvc/errors` pages genuinely full-width for the first time.
+- **Put Talos page CSS in `style.css`, not a page-local `<style>` block.** The Contracts page **returns early** for list mode, so a `<style>` block placed after that return applied to the calculator only and the list rendered with no CSS at all.
+- **Voice multipliers (0.25 / 0.50) are UNVALIDATED** — supplied second-hand, never measured, and possibly inverted. Flagged in the UI. **Do not quote voice from them.** Superseded for per-interaction voice by the `voiceCostPerMinute` factor (see pricing-cogs-model).
+- **`pricingModel` is an enum/FIELD_LIST — validate it in PHP before save.** MySQL silently stores **NULL** for an unknown enum value, so `contracts/post.php` must check the incoming value against the allowed set (`PER_USER`/`PER_INTERACTION`) before saving, and re-validate the locked stored value on a signed row. (General 2.0 rule: `security.md` "Enum columns need validating in PHP".)
+- **Security — two HIGH fixed on the contract page (cso, 2026-09-17):** (a) a signed contract could **flip its `pricingModel` on resubmit** to dodge the other model's minimum-field validation — the "locked at signing" override must run **before** per-model validation; (b) `clientIdentifier` (the AWS cost/usage join key) was only readonly client-side — it **must be re-pinned server-side** once signed, or a resubmit can misattribute a tenant.
 - **`db_team`** is read/write on Contracts and Settings, read-only on the dashboards.
-- **Chart.js colours must come from theme tokens, and a live theme switch needs
-  `chart.update()`.** These pages now read series/axis/tick/gridline colours via
-  `TogaTheme.color('--c-…')` inside a `paint()` registered with `TogaTheme.onChange(paint)`,
-  then call `chart.update()` — `update()` clears Chart.js's resolver cache, so without it a
-  `Chart.defaults` change does not reach charts that already exist. Chart.js otherwise defaults
-  axis/tick text to a dark colour that is unreadable in dark mode. See
-  [App-Wide Colour Theme](./theme-light-dark.md).
-- **These pages keep an explicit `--c-bs-*` token group** because they were authored against
-  Bootstrap's palette (`#0d6efd`, `#6c757d`, `#495057`, `#dc3545`, `#198754`…), which is close
-  to but not the TOGA brand palette — folding them into `--c-primary` visibly restyles them.
-- **Open (dark mode):** the error toast measures ~2.4:1 (white on `--c-danger`) and likely
-  wants a fixed dark fill; the Pricing Dashboard target-band dataset never had a
-  `backgroundColor` (pre-existing authoring slip) so the band shades rather than tints; the
-  three chart pages cannot be statically proven light-identical and still need a browser pass.
-
-## Security
-- `config.*.ini` carries committed plaintext secrets (team-accepted, see architecture Known
-  issues) — **all still owe rotation**. Config keys referenced by name only
-  (`[api] talos_backend_url` / `talos_backend_key`); no values recorded. Do not add secrets.
+- **Chart.js colours must come from theme tokens, and a live theme switch needs `chart.update()`.** These pages now read series/axis/tick/gridline colours via `TogaTheme.color('--c-…')` inside a `paint()` registered with `TogaTheme.onChange(paint)`, then call `chart.update()` — `update()` clears Chart.js's resolver cache, so without it a `Chart.defaults` change does not reach charts that already exist. Chart.js otherwise defaults axis/tick text to a dark colour that is unreadable in dark mode. See [App-Wide Colour Theme](./theme-light-dark.md).
+- **These pages keep an explicit `--c-bs-*` token group** because they were authored against Bootstrap's palette (`#0d6efd`, `#6c757d`, `#495057`, `#dc3545`, `#198754`…), which is close to but not the TOGA brand palette — folding them into `--c-primary` visibly restyles them.
+- **Open (dark mode):** the error toast measures ~2.4:1 (white on `--c-danger`) and likely wants a fixed dark fill; the Pricing Dashboard target-band dataset never had a `backgroundColor` (pre-existing authoring slip) so the band shades rather than tints; the three chart pages cannot be statically proven light-identical and still need a browser pass.
+- **Security:** `config.*.ini` carries committed plaintext secrets (team-accepted, see architecture Known issues) — **all still owe rotation**. Config keys referenced by name only (`[api] talos_backend_url` / `talos_backend_key`); no values recorded. Do not add secrets.
 
-## Change history
-- 2026-08-04 — Tokenised these pages for the new app-wide light/dark theme: page-local styles
-  now use `--c-*` tokens (Talos pages keep their own `--c-bs-*` Bootstrap ramp), and the three
-  Chart.js pages read colours via `TogaTheme.color()` + repaint on `TogaTheme.onChange()` with
-  `chart.update()`. Recorded the dark-mode open items (error-toast contrast, missing
-  target-band `backgroundColor`). Not committed. (jcardinal)
-- 2026-08-04 — Restructured to **Contracts / Pricing Dashboard / Usage / Pricing Settings**. New Contracts pages replace Onboarding with a real PROSPECT/ACTIVE/CHURNED lifecycle (signed contracts churn, never hard-delete — `TalosPricingBands` cascades; post-signature edits append to `TalosContractAmendments`), plus actual-vs-estimate variance, month history chart and one-click apply-recommended-org-fee. Settings replaces the Cost Factors editor with measured rows read-only (`UPDATE ... AND isDerived = 0`). Benchmarks page deleted. Pricing Dashboard rebuilt for sales leadership. Fixed `usage.php clientOptions()` reading an always-empty `TalosClients` (selector rendered empty) → `GET /api/usage/clients` with Team-DB fallback; added cost-intensity panel. Estimator moved to token unit price + workload profiles. Wrote the missing `.app-content:has(.tool--wide)` rule and consolidated Talos CSS into `style.css`. (jcardinal)
-- 2026-06-29 — Built the Talos Pricing UI: nav folder + 4 pages (Onboarding w/ live JS estimate and contract-signing that locks the band schedule into `TalosClients`+`TalosPricingBands` in one txn; read-only Pricing Dashboard + Usage Benchmarks; technical-only Cost Factors editor) and `App_Talos_Estimator` (reads `TalosCostFactors`, derives conversations/user so sales need not enter it). Reads Team DB via new `db_team` connection. Offerings CHAT/VOICE_TO_VOICE/NATURAL_VOICE = 1.0/0.25/0.50 (voice ambiguous, deferred). (jcardinal)
+## Related
+- [App-Wide Colour Theme](./theme-light-dark.md)
+- [Persona-gated navigation](./persona-gated-navigation.md)
+- [Tools MVC — data-access patterns](./mvc-data-access-patterns.md)
+- [Tools architecture](../architecture.md)
+- [Talos architecture (2.0)](../../../2.0/apps/talos/architecture.md)
+- [Pricing COGS model (2.0)](../../../2.0/apps/talos/features/pricing-cogs-model.md)
+- [Talos pricing automation (worker2)](../../../2.0/apps/worker2/features/talos-pricing-automation.md)

package/knowledge/1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-09-15
+updated: 2026-09-17
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -24,6 +24,7 @@ files:
   - dbchanges2/Client/2026-09-02b - NetsuiteSyncCursorRename.sql
   - test/@srija/Elite Testing/Service Requests/test_sync_togasupply_elite_section.php
   - test/@srija/Elite Testing/Service Requests/test_diagnose_togasupply_elite.php
+  - dbchanges2/_modules/netsuite/2026-09-17a - StaleSalesOrderRetirementAcl.sql
 related:
   - ../architecture.md
   - ../../../2.0/apps/_underscore/features/shipping-carriers-and-accounts.md
@@ -34,6 +35,8 @@ related:
   - ../../../clients/elite/features/netsuite-togasupply-sync.md
   - ../../library/features/netsuite-item-class-sync.md
   - ../../../clients/compass-usa/features/sales-order-line-renumbering.md
+  - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
+  - ../../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md
 ---
 
 ## Summary
@@ -97,6 +100,24 @@ its IDLE write. **There is no timeout, memory cap, or resource limit anywhere in
 in prod* (see below), never *tune the window size down*. (Corollary: a window that has grown back to
 the cap is positive evidence the section is completing.)
 
+#### Reading `NETSUITE_EXECUTION_MODE_<SECTION>` at a glance (2026-09-17)
+
+The value is `<seconds>-<STATE>`. Three readings, and only the first is a real freeze:
+
+- **`1-RUNNING`** (window collapsed ÷3 to 1s) = throwing on **every** run = real freeze. Go read the
+  error (`Logs.Event` by clientId → file:line → `Logs_<Client>.Api` on the transactionId).
+- **A large-window `*-RUNNING`** (e.g. `864000-RUNNING`, `288000-RUNNING`) = healthy mid-run **or** a
+  deliberate pause/backfill — **NOT** stuck. Do not "fix" it.
+- **`IDLE` + cursor frozen exactly at a reset value + NO error events = the section toggle is off**
+  (`IS_ENABLED_INTEGRATION_<SECTION> = false` in the wrapper). Resetting the cursor does **nothing**
+  while the toggle is off. Worked example: NYCHH SALES_ORDERS looked "stuck" after a cursor reset to
+  2020-01-01, but `sync_togasupply_hh.php:33` had `IS_ENABLED_INTEGRATION_SALES_ORDERS = false`;
+  re-enabling it (line 33 `true`) made the cursor advance immediately.
+
+Before calling any section stuck, **check for error events first.** The developer routinely rewinds
+cursors (and re-enables feeds) after fixes and to prioritize data, so a cursor sitting years back
+(e.g. NYCHH IF/receipts rewound to 2023) can be an intentional backfill, not a fault.
+
 **Where the error is: prod `Logs.Issue` / `Logs.Event`, NOT Sentry.** Read worker errors from the
 production log DB by default — you do not need a developer to point you there. The base `Logs`
 schema (prod-logs cluster) holds `Issue` (deduped, with `errorMessage` + `trace`) and `Event` (each
@@ -711,6 +732,123 @@ nested count:
   line the fulfillment referenced, the match failed, and the section fail-loud-froze. The flat list
   replaces the truncated nested one before match/reconstruct.
 
+### Retiring the stale SalesOrder a reclassified TransferOrder leaves behind (2026-09-17, NOT YET DEPLOYED)
+
+**Turning transfer-order detection on for an existing client strands every order it already
+imported as a SalesOrder.** The same NetSuite order now syncs to a `TransferOrder`, but the old
+`SalesOrder` is never cleaned up. Its lines still carry fulfillments, so inventory **double-counts**
+and `Items._qtyOnHand` goes negative. Measured on Elite: **218** SalesOrders duplicate a
+TransferOrder on `c_netsuiteInternalSalesOrderId`, and **217 of 217** matched pairs are identical on
+order number, line count *and* total quantity.
+
+`App_Api_Toga2::retireStaleSalesOrderForTransferOrder()` (new, `private static`) is called at the
+**END** of `syncTransferOrderFromNetsuite()` so the TO and its lines exist first. Per SO line:
+
+1. move `ItemFulfillmentItems`: `salesOrderItemId` → `transferOrderItemId`,
+2. move `PurchaseOrderItems_SalesOrderItems` → `PurchaseOrderItems_TransferOrderItems`,
+3. `DELETE` the `SalesOrderItem`;
+
+then move `SalesOrders_PurchaseOrders` → `PurchaseOrders_TransferOrders` and `DELETE` the
+`SalesOrder`. **Move before delete, always** — the bridge FKs are `RESTRICT`.
+
+**The two fulfillment-parent columns are mutually exclusive, which is what makes the move safe.**
+Prod check: 391 rows TO-side, 293 SO-side, **0 with both, 0 with neither**.
+
+**It throws — never skips — on:** more than one SalesOrder for the NetSuite id; a TO with no
+lines; an SO line with no matching TO line; a line carrying `InvoiceItems` (**`InvoiceItems` has no
+`transferOrderItemId`**, so they physically cannot be moved); or any bridge whose existence check
+returns no `totalRecordCount` (see the ACL shape below). Consistent with the 2026-08-27 fail-loud
+policy.
+
+**Bridge direction is PO-FIRST, confirmed from NYCHH data rather than guessed.** The naming rule is
+`<source>_<created from it>`. `Client_Nychh` populates `PurchaseOrderItems_TransferOrderItems` (98
+rows) and `PurchaseOrders_TransferOrders` (45); the TO-first siblings are **0 in every client**. Same
+rule as the [SO↔PO bridge direction doc](../../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md).
+
+**⚠ It needs the three-layer ACL grant first.** Without `AclFieldPermissions` on records 29/325/329
+the bridge existence checks return **200 + `WZ-1` with no `meta.totalRecordCount`** and the method
+throws while blaming record ACL — the exact trap documented on the
+[ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md). The
+fleet-wide grant is `dbchanges2/_modules/netsuite/2026-09-17a - StaleSalesOrderRetirementAcl.sql`.
+
+**Open, carried forward:**
+- Elite SalesOrder **240734** has 4 `InvoiceItems` and **will throw** on retirement. Deliberate
+  fail-loud; it blocks the backfill until resolved by hand.
+- **11 of the 218** stale SalesOrders have no matching TransferOrder (4 are TOGa-created `SA1000xx`
+  with no NetSuite id). Manual review.
+- `getTransferOrderItemsByUuid()` (`toga2.php` ~L4555) has **no pagination** — it caps at
+  `recordsPerPage` 1000, unlike its paginated sibling `getSalesOrderItemsBySalesOrderUuid()`. It is
+  load-bearing for this method's safety. Skipped for now because Elite TOs are 1–5 lines; flagged by
+  php-reviewer.
+
+### ⚠ TWO code paths create `PurchaseOrderItems` — only one stamped `fulfillmentType` (fixed 2026-09-17)
+
+`fulfillmentType` was stamped by `syncPurchaseOrderFromNetsuite()` (from the order-level
+`isDropShipPurchaseOrder`) but **not** by the **customer-PO block inside
+`syncSalesOrderFromNetsuite()`**, at three POST sites. Those customer POs are built from the NetSuite
+sales order's `otherRefNum` against the synthetic Agilant vendor, so they carry a `customerId` but a
+**NULL `c_netsuiteInternalPurchaseOrderId`** — which is how to spot them. **1,038 of 1,113** NULL
+`fulfillmentType` PO lines came from this path, so **no cursor rewind would ever have fixed them**;
+the rewind only replays the other path.
+
+Fix: stamp `fulfillmentType` (inherited from the SO line, exactly as `cost` already is) at all three
+create sites, plus a **backfill PUT on the matched-existing-line branch** so pre-existing rows fill
+in on the next sync. Gated by `isset()` on the payload key so non-opted-in clients send nothing, and
+the backfill uses `property_exists` (not `??`) per this file's established ACL-omission rule — an
+ungranted field is **absent**, not null.
+
+**Lesson: before concluding "the backfill is lagging", grep for every writer of the column.** A
+second, un-stamped create path looks identical to a stale cursor from the data side.
+
+### ⚠ A stale child list read at run-start causes FK 1451 on a delete LATER IN THE SAME RUN (fixed 2026-09-17)
+
+`NETSUITE_EXECUTION_MODE_ITEM_FULFILLMENTS` decayed `864000 → 1186 → 396`, stuck `RUNNING`, with one
+item (`b96515b3`) failing five consecutive runs ~every 5 minutes. **Not self-correcting.**
+
+```
+EV-11 ... Error #: 1451 Cannot delete or update a parent row: a foreign key constraint fails
+(Client_Elite.ItemFulfillmentItems_TrackingNumbers ...)
+```
+
+**Root cause is ordering inside a single run, not stale data between runs.** The delete reads an
+item's tracking rows from `$itemFulfillment`, fetched at the **top** of the run — but the tracking
+pass **later in the same run** creates new tracking rows against those same items. The run-start
+snapshot misses them, the child delete skips one, and the item delete hits the FK. Prod proof:
+tracking `0ddc9513` created at **03:31:18**, the item delete failed at **03:31:21** — three seconds
+apart.
+
+Fix, applied at **both** item-level delete sites: **re-read the item's tracking rows live**
+(`GET /v2/item-fulfillment-item-tracking-numbers` joined on `ItemFulfillmentItems.uuid`) immediately
+before deleting, instead of trusting the run-start snapshot — the same re-fetch pattern this file
+already uses for the single-tracking-number fan-out. A `totalRecordCount` guard was added to both.
+
+**Scope was confirmed, not assumed:** every FK-1451 failure that day was on
+`/v2/item-fulfillment-items/` — **zero** on units or tracking rows — so the unit-level lists were
+deliberately left alone.
+
+The exception was **not** swallowed. `send()` throws by default; the throw aborted the run and left
+the mode `RUNNING`. That is the designed fail-loud behaviour working correctly.
+
+**General rule for this engine: any list used to delete children must be re-read immediately before
+the delete if ANY later pass in the same run can create more of them.** A run-start snapshot is only
+safe for read-only use.
+
+### ⚠ NULL `fulfillmentType` on SO lines can be CORRECT ROUTING, not a sync bug (2026-09-17)
+
+"684 `SalesOrderItems` have NULL `fulfillmentType`" looked like a defect and was not. Ruled out in
+order — record these so nobody re-walks them:
+
+1. backfill lag — no,
+2. the `property_exists` gate — no,
+3. ACL on the field — grants exist (`recordFieldId` **2594/2595**, roleId 3, `isWritable = 1`),
+4. a cursor timezone theory — **wrong**; the code correctly uses `America/New_York`.
+
+**Actual reason:** those orders are now classified as **Transfer Orders** (`$0` + `holdInvoice`), so
+the sync routes them to `syncTransferOrderFromNetsuite()` and they never reach the sales-order path
+that stamps the field. The rows are stranded leftovers — exactly what the retirement method above
+cleans up. **When a per-line field is NULL on a set of orders, check the routing branch before the
+writer.**
+
 ### Custom field contract (hardcoded in `common_sync_togasupply.php`)
 
 The engine requests these `c_` fields by literal name per route — every synced client must have
@@ -1561,6 +1699,39 @@ library (or vice versa) crashes GroWrk and Adyen on their next sync run.
   SalesOrders" branch, classify the order authoritatively (`App_Api_Netsuite_Rest::fetchSalesOrderByIdFull`
   + `self::isTransferOrder`) and **return early** when it is a transfer order, gated on
   `IS_ENABLED_INTEGRATION_TRANSFER_ORDERS`. Existing TO-billed invoices were deleted by the developer.
+- **⚠ The invoice's billed-SO lookup must be PER-CLIENT scoped — the `==1` guard false-throws for a
+  client that keeps two SalesOrders per NetSuite id (fixed + deployed 2026-09-17, Compass).**
+  `syncInvoiceFromNetsuite` (`library/app/api/toga2.php` ~L3326-3339) looked up the billed sales order
+  by `c_netsuiteInternalSalesOrderId` **only** and required `meta->totalRecordCount == 1`. Compass keeps
+  **two** `SalesOrders` rows for one NetSuite id — the Office-Depot-created `customerId=1` order and the
+  NetSuite-synced `customerId=3` order — so the lookup returned 2, failed the `==1` check, and the
+  fail-loud dependency guard threw *"refusing to import invoice … its billed sales order … is not
+  imported in toga"* (prod `Logs.Issue` 792, clientId 2, INVOICES stuck `96000-RUNNING`, cursor
+  ~2026-08-20) even though the correct order (id 97932, `customerId=3`, `locationId=615286`) was present.
+  **Fix:** add a per-client scope block to this lookup **mirroring** `syncSalesOrderFromNetsuite` (~L974-987)
+  and `syncItemFulfillmentFromNetsuite` (~L5197-5204) — Compass adds `SalesOrders.locationId=615286` +
+  `customerId=3`; Prudential adds the `Customers` join + `CLIENT_UUID_PRUDENTIAL_CUSTOMER`; no other client
+  changed, no else/default, and the guard still throws for a genuinely-missing SO. PHP 7.2-safe
+  (`$options['join'] ?? []`), signature unchanged.
+  - **⚠ OPEN follow-up (own ticket): six OTHER clients also keep two SalesOrders per NetSuite id, and the
+    fix does NOT scope them.** A read-only sweep found the same dual-SO pattern in **Growrk (2789), Canon
+    (2890), Endeavorhealth (4828), Spglobal (2893), Browardsheriff (160), Masonite (17)** (Nychh/Elite/Quad/Sbasite
+    = 0; Compass 28377). Dormant today — only Compass is actually throwing the invoice guard (0 "refusing to
+    import invoice" events for any other client in the last 5 days) — but if any of those six ever bills an
+    invoice against a duplicated SO it will false-throw the same way, and **their duplicates have a DIFFERENT
+    cause than Compass's Office-Depot dual-source.** Also a data-quality question: why do six non-Compass
+    clients have duplicate SalesOrders rows at all.
+- **⚠ ITEM_RECEIPTS auto-creates a warehouse Location — the client's `LocationTypes` MUST have a
+  "Warehouse" row or it EV-12-freezes (fixed 2026-09-17, Prudential).** `syncItemReceiptFromNetsuite`
+  (`library/app/api/toga2.php`) `POST /v2/locations` with `locationType.uuid = WAREHOUSE_LOCATION_TYPE_UUID
+  = 78c24f51-b33b-438b-e3f2-b6232d9ecb75` (:3997). `Client_Prudential.LocationTypes` had only a "Shipping"
+  row — no "Warehouse" — so the reference didn't resolve → **EV-12** (prod `Logs.Issue` 757, clientId 5,
+  ITEM_RECEIPTS `1-RUNNING`, cursor stuck 2026-09-14 15:12:43; confirmed via `Logs_Prudential.Api` `POST
+  /v2/locations` 400). **Fix:** guarded/re-runnable INSERT of the Warehouse `LocationTypes` row using the
+  **same literal uuid every client uses** (the documented shared-lookup-uuid exception to "uuids must be
+  random"; `Client_Nychh` has it as id 2) —
+  `dbchanges2/Client_Prudential/2026-09-17 - SeedWarehouseLocationType.sql`. **The live `LocationTypes`
+  column is `name`, NOT the older `type`.** The section self-heals once the row exists (no manual mode reset).
 - **⚠ ROOT CAUSE of the duplicate `Items`: the inventory-adjustment item-create OMITTED the catalog
   (fixed 2026-08-31).** `getCreateItem` (`toga2.php:6233`) and the fulfillment create (~4951) stamp
   `'catalog' => ['name' => 'Agilant']`; `syncInventoryAdjustmentFromNetsuite`'s item-create did **not** →
@@ -1653,6 +1824,38 @@ library (or vice versa) crashes GroWrk and Adyen on their next sync run.
   [NetSuite Sync Alert Monitor](../../library/features/netsuite-sync-alert-monitor.md).
 
 ## Change history
+- 2026-09-17 — **Cross-client sync-freeze debugging (Compass / Prudential / NYCHH / Elite).**
+  (1) **Compass INVOICES** unfrozen (`96000-RUNNING`, `Logs.Issue` 792): `syncInvoiceFromNetsuite`'s
+  billed-SO lookup keyed on `c_netsuiteInternalSalesOrderId` with a `==1` guard, but Compass keeps two
+  `SalesOrders` per NetSuite id (ODP `customerId=1` + synced `customerId=3`) → lookup returned 2 →
+  false-throw. Added a per-client scope block mirroring the SO/IF paths (Compass `locationId=615286`+`customerId=3`;
+  Prudential `Customers` join). php-reviewer + cso clean, deployed. **Open follow-up (own ticket):** six other
+  clients (Growrk/Canon/Endeavorhealth/Spglobal/Browardsheriff/Masonite) have the same dual-SO pattern from a
+  different cause and are NOT scoped by this fix — dormant today. (2) **Prudential ITEM_RECEIPTS** unfrozen
+  (`Logs.Issue` 757, EV-12): the receipt sync auto-creates a warehouse Location, but `Client_Prudential.LocationTypes`
+  had no "Warehouse" row → seeded it via `dbchanges2/Client_Prudential/2026-09-17 - SeedWarehouseLocationType.sql`
+  (shared-lookup-uuid; live column is `name`), deployed, section self-healed. (3) Recorded the
+  **execution-mode reading key** (`1-RUNNING` = real freeze; large-window `*-RUNNING` = healthy/paused;
+  `IDLE`+frozen-at-reset+no-errors = toggle off) — NYCHH SALES_ORDERS looked stuck but was toggled off at
+  `sync_togasupply_hh.php:33`; re-enabling advanced the cursor. (jcardinal)
+- 2026-09-17 — Four importer changes, all found on Elite. (1) New
+  `App_Api_Toga2::retireStaleSalesOrderForTransferOrder()` retires the stale `SalesOrder` left
+  behind when an order is reclassified as a TransferOrder — 218 Elite duplicates were
+  double-counting inventory and driving `_qtyOnHand` negative; it moves fulfillments and PO bridges
+  to the TO side before deleting, and throws on `InvoiceItems` (no `transferOrderItemId` exists).
+  Bridge direction confirmed **PO-first** from NYCHH row counts. **NOT yet deployed.** (2) The
+  customer-PO block inside `syncSalesOrderFromNetsuite()` never stamped `fulfillmentType` at its
+  three POST sites — 1,038 of 1,113 NULL PO lines came from that second writer, so no cursor rewind
+  could fix them; added the stamp plus a backfill PUT on the matched-line branch. (3) ITEM_FULFILLMENTS
+  froze on **FK 1451 / EV-11** because the tracking-row list was read at run start while a later pass
+  in the **same run** created more rows; both item-level delete sites now re-read tracking live before
+  deleting. (4) Recorded that a NULL per-line `fulfillmentType` can be correct **routing** (the order is
+  now a Transfer Order) rather than a sync bug, with the four dead ends already ruled out. Also noted the
+  PO-sync unfreeze needed a three-layer ACL grant — the field layer fails as a silent 200, see the
+  [ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md).
+  php-reviewer + silent-failure-hunter clean; one open warning (`getTransferOrderItemsByUuid()` has no
+  pagination). (rgirish)
+
 - 2026-09-15 — Added the **full resync recipe** for a deep cursor rewind (the procedure for
   backfilling a newly-stamped item field): the six `NETSUITE_LAST_SYNC_CURSOR_<SECTION>` keys live in
   the **client** DB, the id half **must be `0`** or the seek skips records at the same datetime, the

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

@@ -17,6 +17,7 @@ files:
   - dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql
   - dbchanges2/Client/2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission.sql
   - dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql
+  - dbchanges2/_modules/netsuite/2026-09-17a - StaleSalesOrderRetirementAcl.sql
 ---
 
 ## Summary
@@ -127,6 +128,92 @@ Two distinct failure shapes, and the second is a page-killer:
    endpoint takes the **entitlement** uuid precisely to avoid requesting the joined
    `subscription.uuid` and betting the whole entitlements page on one more grant.
 
+### ⚠⚠ Record access + ZERO readable fields = HTTP **200**, `WZ-1`, and **NO `meta.totalRecordCount`**
+
+The third layer of the chain fails in a shape nothing else does, and it costs hours because
+**nothing lands in the API error log — the call succeeded.**
+
+With `AclRecordPermissions` + expression + logic group all correct, but **no `AclFieldPermissions`
+rows at all** for that role × record, a GET returns:
+
+- HTTP **200** (not 403, not `EZ-2`),
+- message **`WZ-1: "There are no fields in which you are authorized to read"`**,
+- and **`meta.totalRecordCount` is OMITTED entirely** from the envelope.
+
+That last point is the killer. Fail-loud importer code commonly guards on
+`if (!isset($response->meta->totalRecordCount)) { throw ... }` as its "the existence check did not
+run" test — so a pure field-layer gap surfaces as that throw, with a message blaming record ACL,
+while the record ACL is in fact fine.
+
+**Distinguish the three failure shapes before touching any grant:**
+
+| Shape | Missing layer |
+|---|---|
+| 403 `EZ-1` / `No ACL Logic Groups defined for ACL Record Permissions` | record permission or logic group |
+| 403 `EZ-2` naming specific fields (incl. a `uuid` you never asked for) | *some* field grants exist, the named one does not |
+| **200 + `WZ-1` + no `meta.totalRecordCount`** | **`AclFieldPermissions` is completely empty for that role × record** |
+
+**Worked case (Elite, 2026-09-17).** Elite's NetSuite PO sync was dead for days:
+`NETSUITE_EXECUTION_MODE_PURCHASE_ORDERS` sat at `1-RUNNING` with 51 lifetime occurrences of
+`linkPurchaseOrderToTransferOrder: PurchaseOrders_TransferOrders existence check returned no
+totalRecordCount (API role likely lacks ACL read/write on this bridge)`. It was **misdiagnosed
+twice**: the first pass added `AclRecordPermissions` for records 29/325/329 plus `allowDelete` on
+14/15, verified all five rows present with logic groups — and it still failed, because
+`Client_Elite` had **zero** roleId 3 rows in `AclFieldPermissions` for those bridges.
+`Client_Nychh` had all six, which is exactly why linking worked there.
+
+The working set that fixed it (mirrors `Client_Nychh`):
+
+| `Core.Records` id | route | granted `RecordFields` (roleId 3) |
+|---|---|---|
+| **325** | `purchase-orders-transfer-orders` | 2210 `uuid`, 2211 `purchaseOrderId`, 2212 `transferOrderId` |
+| **329** | `purchase-order-items-transfer-order-items` | 2226 `uuid`, 2227 `purchaseOrderItemId`, 2228 `transferOrderItemId` |
+| **29** | `item-fulfillment-items` | 366 `uuid`, 367 `itemFulfillmentId`, 368 `salesOrderItemId`, 369 `quantity`, 2151 `transferOrderItemId` |
+
+**`id` (2209 / 2225 / 365) is deliberately NOT granted** — NYCHH does not grant it either, and the
+sync joins on `uuid` throughout precisely because the numeric `id` is not ACL-readable. Do not "fix"
+its absence.
+
+Result after deploy: `PurchaseOrders_TransferOrders` went **0 → 17** rows and
+`PurchaseOrderItems_TransferOrderItems` **0 → 28** (populated for the first time ever); the PO mode
+recovered to `864000-IDLE` and the cursor moved 2026-02-03 → 2026-03-28.
+
+**Rule: when you add a record grant, add the field grants in the same migration.** A record
+permission with no field permissions is not a partial grant — it is a grant that reads as a
+successful, empty, count-less response.
+
+### ⚠ A multi-client ACL migration must SELF-HEAL — every tenant is broken differently
+
+Do not write a fleet-wide ACL migration as "insert the rows the reference client has." Surveying
+five `netsuite` clients on 2026-09-17 found **five different broken states** for the same set of
+records:
+
+| Tenant | State found |
+|---|---|
+| **NYCHH** | complete and correct — the reference |
+| **Elite** | records 325/329 missing entirely |
+| **GroWrk** | 325/329 missing **and** record 15 has a permission with **zero logic groups** (silently denies) |
+| **Prudential** | 325/329 exist **twice each** (duplicate permission rows), no expressions, no logic groups |
+| **Canon, Quad** | only 14/15, both with `allowDelete = 0` |
+
+The six-step shape that survives all of them — every step `NOT EXISTS`-guarded and re-runnable:
+
+1. `UPDATE` `allowDelete = 1` on the records that already have permissions (14/15).
+2. `INSERT` `AclRecordPermissions` for the missing records (29/325/329).
+3. `INSERT` `AclRecordExpressions` `'all'` for **all five** records — not just the new three.
+   Prudential already had permissions on 325/329 with **no expression**.
+4. `INSERT` `AclLogicGroups` for **any** permission lacking one — this is what catches GroWrk's
+   orphan permission and Prudential's duplicates, which a "new records only" migration walks past.
+5. `INSERT` `AclLogicGroupExpressions` joining on **`MIN(id)` per record**, not on the expression
+   slug. Prudential has **three** `'all'` expressions on record 14; joining by slug alone fans out
+   into a cross product.
+6. `INSERT` `AclFieldPermissions` — the layer the first attempt missed (see the section above).
+
+**The `MIN(id)` and orphan-logic-group guards came from real production rows, not from theory.**
+Before writing a fleet migration, survey the tenants and let the worst state design the guards.
+Applies to every module that ships to many clients (this one goes to all **22** clients carrying
+`netsuite` in `dbchanges2/_modules.txt`).
+
 ### ⚠ Resolve `Core.RecordFields` ids by HARDCODED LITERAL in a `Client_*` migration — the subselect cannot run
 
 This **overrides** the general "resolve by subselect, never hardcode" rule *for Core lookups from a
@@ -771,6 +858,16 @@ 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-17 — Added the **field-layer silent-200** failure shape: record access with **zero**
+  `AclFieldPermissions` rows returns HTTP **200** carrying `WZ-1` and **omits**
+  `meta.totalRecordCount`, so fail-loud code that guards on that key throws while blaming record
+  ACL — and nothing appears in the API error log because the call succeeded. Verified on
+  `Client_Elite` (records 29/325/329, roleId 3) after the bug was misdiagnosed twice as a record
+  permission gap; recorded the exact `RecordFields` granted (and that `id` is deliberately not).
+  Also added the **self-healing fleet migration** rule — a survey of five `netsuite` tenants found
+  five different broken states (missing rows, an orphan logic group, duplicate permissions,
+  `allowDelete = 0`), so a multi-client ACL migration must guard every step with `NOT EXISTS` and
+  join logic-group expressions on `MIN(id)` per record rather than on the expression slug. (rgirish)
 - 2026-09-17 — Added the **restrictive-expression-is-dead** rule: permissions are collected per role
   and **any** match authorizes, so a row-restricting expression on one role is cancelled by an `'all'`
   grant on another role the same user holds. Verified in `Client_Compass`: expression **235** on role

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-14
-owners: [snaredla, jcardinal, bala, apeterson]
+updated: 2026-09-17
+owners: [snaredla, jcardinal, bala, apeterson, rgirish]
 files:
   - _underscore/Model.php
   - _underscore/Model/Client/PurchaseOrder.php
@@ -21,6 +21,8 @@ files:
   - _underscore/Model/Quad/Item.php
   - _underscore/Model/Quad/VendorItem.php
   - _underscore/Model/Nychh/Unit.php
+  - _underscore/Model/Client/Item.php
+  - _underscore/Model/Elite/Item.php
   - dbchanges2/Client_Nychh/2026-09-10a - UnitsForPoTableViewRebaseAndTransferLocationField.sql
   - dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql
   - dbchanges2/Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql
@@ -35,6 +37,7 @@ related:
   - ./sales-order-purchase-order-bridge-direction.md
   - ../../../../clients/nychh/features/location-shipping-addresses.md
   - ../../toga25-supply/features/transfer-orders-page.md
+  - ../../../clients/elite/features/inventory-quantities-drop-ship.md
 ---
 
 ## Summary
@@ -218,6 +221,26 @@ 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::`.
 
+### ⚠ `_Model_Client_Item`'s four composites were `self::` until 2026-09-17 — 25 client models affected
+
+A live instance of the `self::` trap above, now fixed, worth knowing because it silently changed
+behaviour for every tenant.
+
+`_Model_Client_Item`'s four **composite** calculated fields — `_qtyOnHand`, `_qtyAvailable`,
+`_qtyBackordered`, `_qtyOnOrder` — built their SQL from the leaf `_qty*` methods using **`self::`**.
+So a client subclass that overrode a *leaf* method (e.g. `_qtyReceived`) had the override **silently
+ignored** by the inherited composites; the only way to make it stick was to re-declare all four
+composites verbatim on the child. `_Model_Client_PurchaseOrderItem` already used `static::`.
+
+Changed to **`static::`** on 2026-09-17, matching the PurchaseOrderItem model. **This affects all 25
+client `Item` models:** any client already overriding a leaf method now has that override picked up
+by the composites for the first time. **`Nychh` overrides `_qtyReceived` and `_qtyCommitted`, so it
+is the one to watch.**
+
+**Lesson for any shared base model:** write composites with `static::` from the start. A `self::`
+composite does not fail — it quietly returns the parent's number, and the child's override looks
+like it "did nothing."
+
 ## 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 —
@@ -268,6 +291,14 @@ Keep the expression cheap, or expect callers to pay for it on every list.
   [save-cascade stored-field deadlocks](./model-save-parent-cascade-stored-field-deadlock.md).
 
 ## Change history
+- 2026-09-17 — Recorded a live instance of the `self::` trap: `_Model_Client_Item`'s four composite
+  fields (`_qtyOnHand`, `_qtyAvailable`, `_qtyBackordered`, `_qtyOnOrder`) used **`self::`**, so a
+  client subclass overriding a *leaf* `_qty*` method was silently ignored unless it re-declared all
+  four composites. Switched to **`static::`**, matching `_Model_Client_PurchaseOrderItem`. This
+  changes behaviour for **all 25 client `Item` models** — `Nychh` (overrides `_qtyReceived` and
+  `_qtyCommitted`) is the one to watch. Found while adding Elite's drop-ship exclusion; see
+  [Elite inventory quantities](../../../clients/elite/features/inventory-quantities-drop-ship.md).
+  (rgirish)
 - 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.