toga-ai 1.0.918 → 1.0.919

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

@@ -17,6 +17,7 @@
 | [Error Capture in 1.0 (App_Error_Capture → shared 2.0 Logs DB)](features/error-capture-1-0.md) | 1.0 error-reporting into the shared 2.0 Logs DB (`App_Error_Capture::captureException`), mirroring 2.0's Issue/Event; open when adding a 1.0 capture path or deb |
 | [HTTP 500 Error Monitor (App_SystemMonitor_500Error) — email-only count; diagnose via error.id](features/http-500-error-monitor.md) | 1.0 monitor `App_SystemMonitor_500Error`: counts `Logs.Api` responseCode=500 in the last 5 min and emails devteam; no ClickUp. |
 | [1.0 MVC Page Pattern & New-App Skeleton](features/mvc-page-pattern-and-app-skeleton.md) | Recipe for a new 1.0 (`App_`) app and for adding pages: folder-based MVC routing, page lifecycle, models, multi-DB config; open when standing up a 1.0 app or ad |
+| [NetSuite Closed sales orders — keep if related records, delete if none](features/netsuite-closed-order-rule.md) | How the NetSuite → TOGa Supply sync treats a Closed SO (all clients): keep + import when anything was created from it, delete when nothing was; plus the ACL the |
 | [NetSuite File Cabinet Content Retrieval via RESTlet (fetchInvoiceFile)](features/netsuite-filecabinet-restlet.md) | How 1.0 pulls NetSuite File Cabinet binary content (invoice PDFs) via a SuiteScript RESTlet (`fetchInvoiceFile`); open when fetching NetSuite file bytes over RE |
 | [assetType from NetSuite itemtype during Item Sync (opt-in per client)](features/netsuite-item-assettype-sync.md) | Stamp `Items.assetTypeId` from NetSuite `item.itemtype` during item sync (opt-in per client, fill-NULL-only); open before enabling asset-type mapping for a clie |
 | [NetSuite classification → ItemClasses sync (opt-in per client)](features/netsuite-item-class-sync.md) | `App_Api_Toga2::getCreateItemClass()` mirrors NetSuite's **classification tree** into the client's `ItemClasses` table and stamps `Items.itemClassId`. |

package/knowledge/1.0/apps/library/features/netsuite-closed-order-rule.md

@@ -0,0 +1,45 @@
+---
+title: "NetSuite Closed sales orders — keep if related records, delete if none"
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-09-30
+owners: ["rgirish"]
+files:
+  - library/app/api/toga2.php
+  - library/app/api/netsuite/rest.php
+  - worker/crons/toga2/netsuite/common_sync_togasupply.php
+  - worker/crons/toga2/netsuite/process_netsuite_order.php
+  - worker/crons/toga2/netsuite/delete_closed_netsuite_orders.php
+related:
+  - ../../worker/features/netsuite-togasupply-per-client-sync.md
+  - ../../worker/workflows/reprocessing-one-netsuite-order.md
+  - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
+  - ../../../clients/compass-usa/profile.md
+---
+
+How the NetSuite → TOGa Supply sync treats a Closed SO (all clients): keep + import when anything was created from it, delete when nothing was; plus the ACL the delete needs.
+
+## Summary
+- **Rule (2026-09-29, all NetSuite sync clients):** a NetSuite SO in status `Closed`:
+  - **with** related records (any transaction whose `createdfrom` is the SO — fulfillment, invoice, PO, return) = **completed**. Keep it and import it like any order, shipments included.
+  - **with none** = **duplicate**. Never import it; delete the TOGa order if it was imported before it closed.
+- **Replaces the 2026-09-23 decision "delete every Closed order".** That rule skipped closed orders that really shipped, so TOGa on-hand stayed above NetSuite.
+
+## How it works
+- `App_Api_Netsuite_Rest::hasRelatedTransactions(int $orderId)` — SuiteQL `COUNT(*)` on `transactionline` where `createdfrom = <id>` and `transaction <> <id>`.
+- `App_Api_Toga2::isNetsuiteOrderClosedWithoutRelatedRecords($nsOrder)` = status `Closed` AND no related transactions. Used by the SO loop in `common_sync_togasupply.php`, `syncTransferOrderFromNetsuite`, and `process_netsuite_order.php`.
+- `App_Api_Toga2::deleteClosedOrderFromNetsuite()` has its own **KEEP guard** (re-checks `hasRelatedTransactions`, logs `KEEP`, returns false). So every caller, including the one-time tool `delete_closed_netsuite_orders.php` (dry run unless `--execute`), is safe.
+- The delete removes the SalesOrder/TransferOrder with its lines, invoices, fulfillments (units, tracking bridges) and bridge rows. Records on the other side of a bridge (PO, other SO, TrackingNumber, Unit) are never deleted — only the link row. Fails loud; a half-done delete is finished by the next run.
+- Backfill for shipped closed orders that were skipped under the old rule: re-run their fulfillments with `process_netsuite_records.php` (see [re-processing workflow](../../worker/workflows/reprocessing-one-netsuite-order.md)).
+
+## Gotchas
+- **The delete reads every route in `CLOSED_ORDER_DELETE_ROUTES` (toga2.php) — the client's API role (roleId 3) needs read on ALL of them:** record permission + an expression on each logic group + field permission (at least `uuid`). One gap throws, and because it runs in the SO loop, **SALES_ORDERS freezes** (and the sections after it). Find gaps per client with `App_Api_Toga2::checkClosedOrderDeleteAccess()` (run by `delete_closed_netsuite_orders.php`; it lists every gap in one run). ACL layers: [acl-permission-chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md).
+  - Worked example (Compass, 2026-09-29): records 312/313 (transfer-orders) had logic groups with no expression; 257 (entitlement-sales-orders) and 254 (sales-order-payments) had no `AclRecordPermissions`, then no `AclFieldPermissions` (`EZ-2` on `uuid`). Fix: `dbchanges2/Client_Compass/2026-09-29a - TransferOrderAclExpressions.sql`. Then reset `NETSUITE_EXECUTION_MODE_SALES_ORDERS` to `864000-IDLE`.
+- Adding a route to `CLOSED_ORDER_DELETE_ROUTES` = a new ACL need on every client. Run the access check fleet-wide before deploy.
+
+## Change history
+- 2026-09-30 — Created. Closed SO with related records is now kept + imported; only Closed with none is deleted (replaces 2026-09-23 "delete every Closed"). Added KEEP guard in the delete and the ACL gotcha from the Compass SALES_ORDERS freeze. (rgirish)

package/knowledge/1.0/apps/library/features/netsuite-suiteql-api-reference.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-09-28
+updated: 2026-09-30
 owners: ["dfranks", "jcardinal", "kyalamarthi", "ajean", "rgirish"]
 files:
   - library/app/api/netsuite/rest.php
@@ -263,8 +263,12 @@ SalesOrd per-id GET counts by `lastmodifieddate` window: ~16,600 (90d) / ~61,900
 - Field/relationship availability varies by NetSuite account **and** record type — probe the live account before assuming a column exists.
 - **`IS NOT NULL` on a custom `transactionline` column inside an aggregate query is a ~15× planner trap — prefer `> 0` (or `NVL(col,0) <> 0`).** Filtering a custom employee-ref column (`custcol_sales_rep_line`) with `AND tl.custcol_sales_rep_line IS NOT NULL` inside a `GROUP BY` / power-sum aggregate (`MOD(SUM(MOD(id*id,P)),P)`) made the planner scan pathologically: **~122s** vs **~8s** for the semantically identical `AND tl.custcol_sales_rep_line > 0` (employee internalIds are always positive) — a ~15× regression purely from the predicate form. Measured against the Forecast2 reconciliation checker (TRUE-79968). Use `> 0` / `NVL(col,0) <> 0` for a custom ref column you only need to test for presence in an aggregate; reserve `IS NOT NULL` for non-aggregate row filters.
   - **⚠ `> 0` is NOT a universal fix — it is column-dependent.** A predicate on a *different* custom column, `tl.custcol_item_sku > 0`, **never returned even as a STANDALONE aggregate** (not just inside the UNION+MOD fingerprint), while `tl.custcol_sales_rep_line > 0` in the same query stayed fast (~8s). Merely **SELECTing** the custom column is cheap either way. **Durable rule when a custom-column predicate hangs:** keep the fast predicates in SQL, **SELECT** the problem column, and apply that gate in **PHP** — do not assume `> 0` will rescue every custom column. (TRUE-79973, `test/@dave/checker.php` / `fixer.php`.)
+- **Inventory quantities: use `aggregateitemlocation`, not `inventorybalance`.** `inventorybalance.quantityavailable` does NOT subtract SO commitments for many items, so it will not match the NetSuite UI. `aggregateitemlocation` gives `quantityonhand` / `quantityavailable` / `quantitycommitted` per item + location and matches the UI — use it to check TOGa inventory against NetSuite (Elite, 2026-09-29).
 
 ## Related
 
 - `netsuite-suiteql-rest-shim.md` — deep field semantics (signs, `tl.id`==line, `iscogs`, ShipItem cost, `createdFrom`) that sit on top of these mechanics.
 - `../../worker/features/forecast2-netsuite-reconciliation.md` — the audit/trueup tooling that consumes this API.
+
+## Change history
+- 2026-09-30 — Gotcha: `inventorybalance.quantityavailable` ignores SO commitments; use `aggregateitemlocation`. (rgirish)

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

@@ -22,5 +22,5 @@
 | [isFulfillable Multi-Client Backfill (all togasupply clients)](workflows/isfulfillable-multi-client-backfill.md) | One-time backfill catching up `Items.isFulfillable` on existing items across all 17 togasupply clients; open when running/re-running it or deciding whether rema |
 | [Deduplicating NetSuite duplicate Items across client DBs (recursive MERGE)](workflows/netsuite-duplicate-items-dedup.md) | Per-client cleanup collapsing duplicate `Items` rows (same `partNumber`) to one canonical via recursive MERGE; open before running it — and read the catalog-bli |
 | [Onboarding a Client to the NetSuite TOGa Supply Sync](workflows/onboarding-client-to-netsuite-togasupply-sync.md) | How to add a new TOGa 2 client to the per-client NetSuite → TOGa Supply importer; open when onboarding a client, and read the vendor-seed / ACL / Parameters-see |
-| [Re-processing one NetSuite order (process_netsuite_order.php operator CLI)](workflows/reprocessing-one-netsuite-order.md) | Run the real SO/TO sync + its vendor POs for ONE NetSuite order on ONE client, without touching cursors; open to heal or debug a single order. |
+| [Re-processing NetSuite orders, fulfillments and receipts (process_netsuite_order.php / process_netsuite_records.php)](workflows/reprocessing-one-netsuite-order.md) | Run the real sync for given NetSuite ids on ONE client, without touching cursors: one order (+ its vendor POs), or a list of fulfillments/receipts. |
 | [Tracing a 1.0 worker cron run in production (no stdout, silent skips)](workflows/tracing-a-worker-cron-run-in-production.md) | How to answer "did this cron run, and what did it do?" on the 1.0 worker tier (no usable stdout, skipped runs leave no trace); open before concluding a cron "ne |

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-25
+updated: 2026-09-30
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -141,6 +141,18 @@ can show an OLD line; trust the newest `Event.context.errorLine` for the real sp
 gives `memoryPeakMb` — a small peak (e.g. 20 MB) rules out "giant record / OOM" and points at a
 plain thrown warning instead.
 
+**Fastest path to the real error (2026-09-29):**
+
+- `N-RUNNING` with N shrinking run after run = that section throws every run. SALES_ORDERS aborts the whole
+  script, so the sections after it freeze too — fix SO first.
+- Read the api2 rejection in `Logs_<Client>.Api`: `responseCode >= 400 AND responsePayload LIKE '%"api":"Agilant"%'`,
+  newest first, `LIMIT 1` + tight date filter.
+- **`Logs.Issue` keeps only the FIRST trace per fingerprint** — its trace can name the wrong client and line.
+  Use `Logs.Event` (has `clientId`) or `Logs_<Client>.Api` instead.
+- Fleet check: one query on prod-client, `UNION` over every `Client_*.Parameters`
+  (`WHERE name LIKE 'NETSUITE_EXECUTION_MODE_%'`). Wrap text columns in
+  `CONVERT(... USING utf8mb4) COLLATE utf8mb4_general_ci` or the UNION fails on mixed collations.
+
 #### Manual reset after the fix: `864000-IDLE` — get both halves right (2026-09-08)
 
 A section self-heals from `1-RUNNING` on its own, but climbing ×3 from a 1-second window back to the
@@ -499,42 +511,13 @@ record; every section behaves the way SALES_ORDERS always did (throw → freeze
 poison record re-tried each run → go read the error). This is an application of the universal
 coding-style rule *never catch-and-silently-ignore*, not a new engine-specific policy.
 
-### WARNING: a `Closed` NetSuite order is SKIPPED BEFORE the transfer-order branch (fixed 2026-09-08)
-
-`common_sync_togasupply.php` (~L746) does
-
-```php
-if ($nsSalesOrder->status === 'Closed') { continue; }
-```
-
-**before** the `isTransferOrder()` branch. So a transfer order that was **closed in NetSuite never
-reaches `App_Api_Toga2::syncTransferOrderFromNetsuite()`**, and that function's existing
-`case 'Closed'` never runs. **`Closed` is the only status the loop drops** - Pending Fulfillment,
-Partially Fulfilled, Billed and Cancelled all pass through and map fine.
-
-There is no other way in. The item-fulfillment route (`syncSalesOrderFromNetsuite`) and 2.0's
-`_Trait_Netsuite_TransferOrder::syncNetsuiteTransferOrder` both need a **fulfillment or item
-receipt**, which an order closed with nothing shipped will never have. Result on NYCHH: **18 transfer
-orders stuck on `Pending`, the oldest from 2022.**
-
-**The fix - a stage-only write from INSIDE the closed block, before the `continue`:**
+### Closed NetSuite orders (rule 2026-09-29)
 
-- new `App_Api_Toga2::updateTransferOrderStageToClosed(&$nsOrder, array &$clientConfiguration): bool`
-  plus the constant `TRANSFER_ORDER_STATUS__CLOSED = 'closed'` (now also used by the `case 'Closed'`
-  in the status switch);
-- called only when `IS_ENABLED_INTEGRATION_TRANSFER_ORDERS` **and** `isTransferOrder()`;
-- it writes **only `transferOrderStage`** - never line items, so the URI-length / **HTTP 414** blowup
-  that the skip exists to avoid cannot happen;
-- a transfer order we never imported is **left alone**, not created.
-
-**Why not just route closed transfers into the full `syncTransferOrderFromNetsuite`:** that function
-**CREATES** a transfer order when it finds none, so it would invent rows out of years-old closed
-NetSuite orders for Adyen, Elite and GroWrk. **17 of the 20 launchers have
-`IS_ENABLED_INTEGRATION_TRANSFER_ORDERS` false**, so nothing changes for them; the three that have it
-true all use `ZERO_DOLLAR_HOLD` detection.
-
-**Status: written, NOT committed and NOT deployed** as of 2026-09-08. Touches `worker` and `library`,
-so both deploy together (the standing rule for this pair).
+A Closed SO **with** related records (fulfillment, invoice, PO…) is completed — imported like any order.
+A Closed SO with **none** is a duplicate — never imported, deleted if already in TOGa. Replaces the
+2026-09-23 "delete every Closed" rule and the 2026-09-08 stage-only `updateTransferOrderStageToClosed`
+(removed). Full rule, KEEP guard and the ACL the delete needs (a gap freezes SALES_ORDERS):
+[netsuite-closed-order-rule](../../library/features/netsuite-closed-order-rule.md).
 
 ### ⚠ An OUT-OF-SCOPE transfer-order destination customer wedged INVENTORY_ADJUSTMENTS — the importer now SKIPS it (fixed + deployed 2026-09-14)
 
@@ -1093,6 +1076,9 @@ discovered per-client.
 scheduled wrapper runs. Uses `NETSUITE_SYNC_LOOKUPS_ONLY` (early return after LOOKUPS in
 `common_sync_togasupply.php`).
 
+**Given fulfillments / receipts, any client:** `process_netsuite_records.php <client> --fulfillment=ids --receipt=ids`
+— same [workflow doc](../workflows/reprocessing-one-netsuite-order.md).
+
 Two CLI scripts written for the Elite backfill live under
 `test/@srija/Elite Testing/Service Requests/` (they are operator tools, **not** scheduled crons —
 do not add them to `cron.worker.sync.json`):
@@ -1771,30 +1757,13 @@ library (or vice versa) crashes GroWrk and Adyen on their next sync run.
     onboarding effort.
   Both are pre-existing and unrelated to this session's fixes.
 
-- **⚠ A serialized unit's OWN location can differ from its receipt line's — auto-create it before the
-  `/units` write or api2 400s EV-12 (fixed 2026-08-29, `library/app/api/toga2.php`
-  `syncItemReceiptFromNetsuite`).** The unit carries its own `custitemnumber_location` (referenced on the
-  `/units` write by `c_netsuiteInternalLocationId`); when that location differs from the receipt line's
-  and isn't provisioned in the client DB, api2 rejects the unit write **EV-12**. The fix now **POSTs
-  `/locations` for the unit's own location before the write**, mirroring the existing item-line location
-  create one level up. Shared/general fix (any client running serialized item receipts), surfaced by
-  **GroWrk** location **1569**. Deployed.
-  - **The inventory-ADJUSTMENT unit path now has the SAME auto-create (fixed 2026-08-30) — it did not
-    before, which froze GroWrk.** `syncInventoryAdjustmentFromNetsuite`'s serialized-unit processing took
-    the unit's location from the inventory number's `custitemnumber_location` (the unit's own current
-    location, falling back to the adjustment line location), but — unlike `syncItemReceiptFromNetsuite` —
-    **never auto-created a missing warehouse**, so `POST /units` failed **EV-12** "unable to find a unique
-    match" on `location` (`searchCriteria c_netsuiteInternalLocationId=1596`; **0 rows** in
-    `Client_Growrk.Locations` for 1596), leaving `NETSUITE_EXECUTION_MODE_INVENTORY_ADJUSTMENTS` stuck at
-    `1-RUNNING`. **Fix:** capture the unit location's NAME (`$unitNetsuiteLocationName` from the
-    `custitemnumber_location` ref, carried in `$unitsToGet` as `netsuiteLocationName`) and, before **both**
-    unit-location reference points (the per-unit PUT-create path and the batch `POST /units` path),
-    `POST /locations` when the id is not already in `$lookupWarehouseByNetsuiteLocationInternalId` and a
-    name is present — same payload as the receipt sync (`name`, `c_netsuiteInternalLocationId`,
-    `locationType = WAREHOUSE_LOCATION_TYPE_UUID`, `isActive=true`, `allowReceiving`/`allowSending=false`),
-    then register it in the warehouse lookup. Guarded by `!isset(lookup[id]) && !empty(name)` so it fires
-    only for genuinely-missing locations and never duplicates. Shared 1.0 path — benefits all
-    serialized-adjustment clients.
+- **The sync NEVER auto-creates a warehouse Location (rule 2026-09-29, all clients).** An unknown NetSuite
+  location throws via `App_Api_Toga2::throwIfUnknownWarehouse()` (toga2.php): "Verify it, create the Location with
+  `c_netsuiteInternalLocationId` = <id>, then rerun." It replaced 7 `POST /locations` spots: receipt pre-check over
+  ALL lines before any write, receipt + adjustment unit paths, TO origin + destination. A person verifies and creates
+  the Location (client needs a Warehouse `LocationTypes` row, shared uuid `78c24f51-b33b-438b-e3f2-b6232d9ecb75`).
+  - **Unit location comes from the receipt/adjustment LINE, not `custitemnumber_location`.** That field is a bin/bay
+    custom list whose ids overlap real location ids, so reading it as a location put units in the wrong warehouse.
 
 - **⚠ The exact api2 rejection detail lives in `Logs_<Client>.Api`, not `Logs.Event` (which TRUNCATES
   it).** When a section throws on an api2 non-success, `Logs.Event` records the error envelope but
@@ -1983,17 +1952,6 @@ library (or vice versa) crashes GroWrk and Adyen on their next sync run.
     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** →
@@ -2086,6 +2044,7 @@ 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-30 — Closed SO rule: keep if related records, delete only if none ([doc](../../library/features/netsuite-closed-order-rule.md)). Sync never auto-creates warehouse Locations (`throwIfUnknownWarehouse`); unit location from the line, not `custitemnumber_location`. Added `process_netsuite_records.php` and the stuck-sync diagnosis path. (rgirish)
 - 2026-09-24 — TO↔PO links: two-direction reconcile (vendor POs no longer upstream; retireStale moves downstream SO links to 326/330); fixed SO downstream line-link deletes on PO re-sync; new `process_netsuite_order.php` + `NETSUITE_SYNC_LOOKUPS_ONLY`. (jcardinal)
 - 2026-09-22 — **The `Logs.Issue` 589 doom-loop's framework root cause is now fully explained and has
   tooling, but this sync is NOT yet patched.** Three independent reasons the 2006 reconnect was dead

package/knowledge/1.0/apps/worker/workflows/reprocessing-one-netsuite-order.md

@@ -1,24 +1,26 @@
 ---
-title: "Re-processing one NetSuite order (process_netsuite_order.php operator CLI)"
+title: "Re-processing NetSuite orders, fulfillments and receipts (process_netsuite_order.php / process_netsuite_records.php)"
 framework: "1.0"
 repo: worker
 project: Worker
 client: shared
 type: workflow
 status: active
-updated: 2026-09-24
-owners: [jcardinal]
+updated: 2026-09-30
+owners: ["jcardinal", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/process_netsuite_order.php
+  - worker/crons/toga2/netsuite/process_netsuite_records.php
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
   - library/app/api/netsuite/rest.php
 related:
   - ../features/netsuite-togasupply-per-client-sync.md
   - ../../library/features/transfer-order-purchase-order-link-reconcile.md
   - ../../../clients/nychh/features/netsuite-transfer-order-import.md
+  - ../../library/features/netsuite-closed-order-rule.md
 ---
 
-Run the real SO/TO sync + its vendor POs for ONE NetSuite order on ONE client, without touching cursors; open to heal or debug a single order.
+Run the real sync for given NetSuite ids on ONE client, without touching cursors: one order (+ its vendor POs), or a list of fulfillments/receipts. Open to heal, debug, or backfill specific records.
 
 ## Summary
 - Manual CLI, **not scheduled** — never add to `cron.worker.*.json`.
@@ -39,14 +41,24 @@ Steps the script runs:
 2. Defines `NETSUITE_SYNC_LOOKUPS_ONLY` and requires the wrapper → `common_sync_togasupply.php` builds config + lookups, then returns before any section.
 3. `--tranid` → `App_Api_Netsuite_Rest::findSalesOrderIdByTranId()` (format-validated).
 4. Refuses an order whose customer / end-user customer does not map to this client.
-5. Closed → `deleteClosedOrderFromNetsuite`; TO (detection mode) → `syncTransferOrderFromNetsuite` (includes the [two-direction PO link reconcile](../../library/features/transfer-order-purchase-order-link-reconcile.md)); else → `syncSalesOrderFromNetsuite`.
+5. Closed with no related records → `deleteClosedOrderFromNetsuite` ([rule](../../library/features/netsuite-closed-order-rule.md)); Closed with related records syncs like any order; TO (detection mode) → `syncTransferOrderFromNetsuite` (includes the [two-direction PO link reconcile](../../library/features/transfer-order-purchase-order-link-reconcile.md)); else → `syncSalesOrderFromNetsuite`.
 6. `listPurchaseOrderIdsCreatedFromOrder()` → `syncPurchaseOrderFromNetsuite` for every vendor PO created from the order.
 
 Verify: grep the PHP error log for `reconcileTransferOrderPurchaseOrderLinks` and `syncPurchaseOrderFromNetsuite: DELETE`.
 
+### Fulfillments / receipts: `process_netsuite_records.php`
+```
+php crons/toga2/netsuite/process_netsuite_records.php <client> --fulfillment=<id>[,<id>] --receipt=<id>[,<id>]
+```
+- Same guards: refuses while `sync_togasupply_<client>.php` runs; `NETSUITE_SYNC_LOOKUPS_ONLY`; no cursor writes; fail-loud.
+- Runs the real `syncItemReceiptFromNetsuite` (receipts first; the receipt sync also syncs its PO) then `syncItemFulfillmentFromNetsuite`.
+- Scope checks: a fulfillment's source SO customer (or end-user customer) must map to this client; with `IS_ENABLED_ITEM_RECEIPT_OWNED_WAREHOUSE_SCOPE` a receipt needs a line at an owned warehouse (`allowReceiving = 1`). Otherwise it throws "refusing to import it".
+- Used 2026-09-29 to backfill 7 Elite closed-order shipments skipped under the old closed rule.
+
 ## Gotchas
 - A TO skipped by the sync (out-of-scope customer) prints `NOT imported` — read the error log, not a script bug.
 - Needs `IS_ENABLED_INTEGRATION_TRANSFER_ORDERS` true in the wrapper for TO routing; otherwise the order syncs as a sales order.
 
 ## Change history
+- 2026-09-30 — Added `process_netsuite_records.php` (fulfillments/receipts by id); Closed routing follows the new keep/delete rule. (rgirish)
 - 2026-09-24 — Created; prod-verified on NYCHH TO 11. (jcardinal)

package/knowledge/INDEX.md

@@ -4,7 +4,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 29 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 30 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 40 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)

package/knowledge/clients/adyen/profile.md

@@ -11,7 +11,7 @@ project: Worker
 client: adyen
 type: profile
 status: draft
-updated: 2026-09-28
+updated: 2026-09-30
 owners: ["rgirish"]
 files:
   - worker/crons/toga2/netsuite/sync_togasupply_adyen.php
@@ -64,7 +64,7 @@ Adyen tests the tracking API on **prod**. `2026-09-22a - AdyenApiTestSeed.sql` s
 - **Why this prevents duplicates:** the sync matches existing rows by `c_netsuiteInternalSalesOrderId` / `c_netsuiteInternalItemFulfillmentId` (`_underscore/Trait/Netsuite/SalesOrder.php`, `ItemFulfillment.php`). It will replace the dummy `SalesOrderItems` (itemId 6).
 - **⚠ Leftovers:** dummy POs `PO-SR%` and vendor `V-TEST-001` still exist for the linked SOs.
 
-**⚠ The Adyen NetSuite sync has never run.** `Parameters` cursors stuck at `2026-08-20 00:00:00|0`, the `Customers` row has no `c_netsuiteInternalCustomerId`, no `Locations`. Set these up before expecting sync data.
+**⚠ The Adyen NetSuite sync has never run.** `Parameters` cursors stuck at `2026-08-20 00:00:00|0`, the `Customers` row has no `c_netsuiteInternalCustomerId`, no `Locations`. Set these up before expecting sync data. **Also (2026-09-30): the launcher `sync_togasupply_adyen.php` is missing the constants `SHIPPING_LOCATION_TYPE_UUID`, `WAREHOUSE_LOCATION_TYPE_UUID` and `NETSUITE_CUSTOM_FIELD_ID__END_USER_CUSTOMER`** (Elite's launcher has them) — add them before the first run.
 
 **How to match an Adyen SR to its NetSuite SO — there is NO shared key.**
 

package/knowledge/clients/compass-usa/profile.md

@@ -21,7 +21,7 @@ project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-09-25
+updated: 2026-09-30
 owners: [jcardinal, bala, tcox, apeterson, dfranks, akhokhani, ajean, rgirish]
 files: []
 related:
@@ -219,6 +219,7 @@ separate, related client (see its own profile).
   the ⚠ rule that **deactivation is raw bulk SQL, so no model hook ever fires on it**.
 
 ## Notes
+- **⚠ SALES_ORDERS froze 2026-09-29 on ACL gaps the closed-order delete hit** (transfer-orders 312/313, entitlement-sales-orders 257, sales-order-payments 254). Fixed by `dbchanges2/Client_Compass/2026-09-29a - TransferOrderAclExpressions.sql`, then mode reset to `864000-IDLE`. Details: [closed-order rule](../../1.0/apps/library/features/netsuite-closed-order-rule.md).
 - **⚠ The 1.0 NetSuite sync links item fulfillments ONLY to `customerId=3` / `locationId=615286`
   SalesOrders (2026-09-16).** This Compass-specific hardcoded scope filter lives in
   `library/app/api/toga2.php` (`syncItemFulfillmentFromNetsuite` ~L5062-5064,

package/knowledge/clients/elite/INDEX.md

@@ -2,7 +2,7 @@
 
 | Doc | Framework | Summary |
 |-----|-----------|---------|
-| [Elite inventory quantities — drop ship is excluded from On Hand / Available ONLY](features/inventory-quantities-drop-ship.md) | 2.0 | Elite's Inventory page showed **negative Qty On Hand / Qty Available** (worst: `SVC-CI-RETAINER-RS` at **-235**). |
+| [Elite inventory quantities — owned-warehouse STOCK lines + Transfer Orders; drop ship excluded](features/inventory-quantities-drop-ship.md) | 2.0 | How Elite's `_qtyOnHand` / `_qtyAvailable` are computed (`_Model_Elite_Item`) so they match NetSuite: only STOCK lines at warehouses Elite owns, plus Transfer O |
 | [Elite — NetSuite → TOGa Supply inbound sync (TRUE-80499 onboarding)](features/netsuite-togasupply-sync.md) | 1.0 | Elite is the 18th client on the shared NetSuite → TOGa Supply importer ([engine](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md)). |
 | [Elite SalesOrder → NetSuite Push (postPost/postPut interceptors → worker2)](features/salesorder-netsuite-push.md) | 2.0 | Elite's event-driven SalesOrder → NetSuite push (postPost/postPut interceptors → worker2); open for the push trigger, interceptor registration, or the 2026-08-2 |
 | [Elite — Sales Order stage change posts a reply on the TOGa Desk (1.0) ticket](features/salesorder-status-togadesk-reply.md) | 2.0 | How an Elite sales-order stage change posts a reply back onto the originating TOGa Desk (1.0) ticket; open for the cross-DB join path or the dedup key. |

package/knowledge/clients/elite/features/inventory-quantities-drop-ship.md

@@ -1,89 +1,49 @@
 ---
-title: "Elite inventory quantities — drop ship is excluded from On Hand / Available ONLY"
+title: "Elite inventory quantities — owned-warehouse STOCK lines + Transfer Orders; drop ship excluded"
 framework: "2.0"
 repo: _underscore
 project: _Underscore
 client: elite
 type: client-feature
 status: active
-updated: 2026-09-17
+updated: 2026-09-30
 owners: [rgirish]
 files:
   - _underscore/Model/Elite/Item.php
   - _underscore/Model/Client/Item.php
+  - worker/crons/toga2/netsuite/sync_togasupply_elite.php
 related:
   - ../profile.md
   - ./netsuite-togasupply-sync.md
   - ../../../2.0/apps/_underscore/features/calculated-sql-fields.md
   - ../../nychh/features/transfer-order-inventory-quantities.md
-  - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
+  - ../../../1.0/apps/library/features/netsuite-suiteql-api-reference.md
 ---
 
-## Summary
-
-Elite's Inventory page showed **negative Qty On Hand / Qty Available** (worst:
-`SVC-CI-RETAINER-RS` at **-235**). Cause: **drop-ship lines are fulfilled but never received into
-stock**, so the base `received - fulfilled` arithmetic went negative.
+How Elite's `_qtyOnHand` / `_qtyAvailable` are computed (`_Model_Elite_Item`) so they match NetSuite: only STOCK lines at warehouses Elite owns, plus Transfer Order lines.
 
-The rule Elite runs on: **exclude drop ship from `_qtyOnHand` and `_qtyAvailable` ONLY.** Every
-other quantity counts **all** lines — a drop-ship line really was ordered and really did ship.
+## Summary
+- **On hand** = received − shipped (STOCK SO lines at an owned location + Transfer Order lines with an owned origin) + adjusted.
+- **Available** = on hand − committed on STOCK SO lines at an owned location − committed on Transfer Order lines with an owned origin (`qtyCommittedTransferOrders`, new 2026-09-29).
+- **Owned** = `Locations.allowReceiving = 1`. Today only Elite Location 1 = NetSuite 196 "Elite" (set by `Client_Elite/2026-09-28e`).
+- Why Transfer Orders: Elite's $0 hold-invoice SOs import as TransferOrders, so their shipped and committed qty sit on `TransferOrderItems` and were ignored before.
+- Verified on prod 2026-09-29 against NetSuite `aggregateitemlocation` (not `inventorybalance` — see [SuiteQL gotcha](../../../1.0/apps/library/features/netsuite-suiteql-api-reference.md)).
 
 ## How it works
+- Private helpers on `_Model_Elite_Item`, used only by the two composites: `qtyFulfilledStockOnly`, `qtyFulfilledTransferOrders`, `qtyCommittedStockOnly`, `qtyCommittedTransferOrders`. Shipped = fulfillment status slug `shipped`.
+- SO lines need `SalesOrderItems.locationId` at an owned location. The Elite sync stamps it from the NetSuite line location (`IS_ENABLED_NETSUITE_LINE_LOCATION`, see [Elite sync](./netsuite-togasupply-sync.md)). Lines shipped from NS 5 "Main" have NULL `locationId` and drop out.
+- Leaf fields `_qtyFulfilled`, `_qtyCommitted`, `_qtyInvoiced`, `_qtyBackordered`, `_qtyOnOrder` stay inherited and count all lines (drop ship included).
+- Base `_Model_Client_Item` composites use `static::` (not `self::`) so this override takes effect — framework-wide, see [calculated fields](../../../2.0/apps/_underscore/features/calculated-sql-fields.md).
 
-Two `private static` helpers on `_Model_Elite_Item`, used **only** by the two composites:
-
-| Helper | Used by |
-|---|---|
-| `qtyFulfilledStockOnly()` | `_qtyOnHand` |
-| `qtyCommittedStockOnly()` | `_qtyAvailable` |
-
-`_qtyFulfilled` and `_qtyCommitted` themselves stay **inherited and unfiltered** — the filtering
-lives in the composites, not in the leaf fields, so anything reading the leaf number still sees the
-true shipped/committed total.
-
-**Quantities that count ALL lines (drop ship included):** `_qtyOrdered`, `_qtyFulfilled`,
-`_qtyInvoiced`, `_qtyBackordered`, `_qtyOnOrder`.
-
-### Two deliberate decisions — do not "improve" either
-
-- **No `GREATEST(..., 0)` floor.** Negatives must stay **visible** so the underlying data problem
-  can be traced. Flooring hides a real defect behind a clean-looking zero. This was decided
-  explicitly, after one iteration.
-- **A NULL `fulfillmentType` is NOT treated as `STOCK`.** Only a line positively marked stock counts
-  toward on-hand. (NULL `fulfillmentType` has its own causes — see the
-  [importer doc](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).)
-
-### The base model had to change too (`self::` → `static::`)
-
-`_Model_Client_Item`'s four composites (`_qtyOnHand`, `_qtyAvailable`, `_qtyBackordered`,
-`_qtyOnOrder`) called their leaf methods with **`self::`**, which silently ignores a child override.
-They were switched to **`static::`** in the same session. That is a **framework-level** change
-affecting **all 25 client `Item` models** — full detail and the NYCHH watch item on
-[FIELD_SQL calculated fields](../../../2.0/apps/_underscore/features/calculated-sql-fields.md).
-
-## Verification
-
-Run against prod data after the change: **0 negatives on all 79 non-service items.** The **7**
-remaining negatives are all `SVC-` service items (received 0, fulfilled > 0), which the developer
-explicitly said to ignore.
+### Decisions — do not "improve"
+- **No `GREATEST(..., 0)` floor.** Negatives stay visible: they mean a missing receipt or an unsynced `fulfillmentType`.
+- **NULL `fulfillmentType` is NOT stock.** Only `'STOCK'` counts.
 
 ## Gotchas / known issues
-
-- **The Inventory TableView still filters services by `(Items.partNumber:excludes:SVC-)`**, which
-  **misses 18 service items** that sit under service `ItemClasses` trees but carry normal part
-  numbers. Undecided and not implemented. Facts established while investigating:
-  - **`_isServiceClass` does not exist** anywhere in the code (grepped all of `Model/` and
-    `Trait/`) — the migration comment referencing it is **stale**.
-  - The table is **`ItemClasses`**, not `ItemClassifications`, and it is a **tree**
-    (`parentItemClassId`).
-  - Service roots are **Lifecycle Services (1)**, **Advisory and Modernization (22)**, **True
-    Partner Services (40)** — but **6 non-service items** sit under the latter two, so matching on
-    root alone is too broad.
+- **Inventory page filter** is data, in `Client_Elite/2026-09-28b`: hides `SVC-`/`SVT-`/`LIC-`/`CON-` parts, AppleCare, service item classes and drop-ship-only items; shows only rows with nonzero on hand or available.
+- **Known gap: Docking 1 is below NetSuite** — RMA return receipts (created from a Return Authorization) are not imported by the sync, so returned stock is missing. Open.
+- Owned-warehouse scope is Elite-only today; other clients have fake "bay" warehouses (see [Elite sync](./netsuite-togasupply-sync.md)).
 
 ## Change history
-- 2026-09-17 — Documented Elite's drop-ship exclusion rule: drop ship is removed from `_qtyOnHand`
-  and `_qtyAvailable` only, via two `private static` helpers, while every other `_qty*` counts all
-  lines; no `GREATEST` floor (negatives must stay visible) and NULL `fulfillmentType` is not treated
-  as stock. Verified 0 negatives on all 79 non-service items in prod. Also recorded the paired base
-  change from `self::` to `static::` on `_Model_Client_Item`'s composites, and the open
-  `partNumber:excludes:SVC-` TableView filter that misses 18 service items. (rgirish)
+- 2026-09-30 — New formula: owned-warehouse (`allowReceiving = 1`) STOCK SO lines + Transfer Order shipped/committed (`qtyCommittedTransferOrders`); verified vs NetSuite `aggregateitemlocation`. Inventory filter 2026-09-28b; RMA receipt gap recorded. (rgirish)
+- 2026-09-17 — Drop ship excluded from `_qtyOnHand` / `_qtyAvailable` only; no floor; NULL `fulfillmentType` not stock; base composites `self::` → `static::`. (rgirish)

package/knowledge/clients/elite/features/netsuite-togasupply-sync.md

@@ -6,7 +6,7 @@ project: Worker
 client: elite
 type: client-feature
 status: active
-updated: 2026-09-24
+updated: 2026-09-30
 owners: ["snaredla", "jcardinal", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/sync_togasupply_elite.php
@@ -409,8 +409,20 @@ configuration problem, and it only appears **after a section catches up** — wh
 Elite's PO backfill just did. **NOT FIXED** (shared file, 22 clients). Full root cause on the
 [engine doc](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
 
+### Elite-only scope flags (2026-09-29) — Elite stock = its own warehouse only
+
+Set in `sync_togasupply_elite.php`; they feed the [inventory formula](./inventory-quantities-drop-ship.md).
+- `IS_ENABLED_ITEM_RECEIPT_OWNED_WAREHOUSE_SCOPE` — a receipt at an owned warehouse (`Locations.allowReceiving = 1`) is Elite stock even when the PO has no Elite customer.
+- `IS_ENABLED_NETSUITE_LINE_LOCATION` — stamps `SalesOrderItems.locationId` from the NetSuite line location. Needs the API-role write grant on that field (`Client_Elite/2026-09-28e`).
+- `IS_ENABLED_SKIP_TRANSFER_ORDERS_FROM_UNKNOWN_WAREHOUSE` — a TO shipped from a non-Elite NS location (e.g. 5 "Main") is skipped + logged instead of throwing.
+- **Only Elite is safe for the owned-warehouse flag today.** Audit 2026-09-29: other clients have fake "bay" warehouses, and Trividia Locations 3/4 hold SBA customers 1171/22311 (open bug). Audit a client's `Locations` before turning it on.
+- Owned today: Location 1 = NS 196 "Elite" (`allowReceiving = 1` via `2026-09-28e`, with its ACL).
+
 ## Gotchas / known issues
 
+- **Data fixes 2026-09-28/29 (`dbchanges2/Client_Elite/`):** `2026-09-28b` inventory filter, `28d`, `28e` (ACL + `allowReceiving = 1` on NS 196), `2026-09-29a - EliteReceiptLinkAndMissingSalesOrder.sql` (relinks receipt 58882 line to PO line 1765; inserts missing SO 289992). 7 closed-order shipments backfilled with `process_netsuite_records.php` after the [closed-order rule](../../../1.0/apps/library/features/netsuite-closed-order-rule.md) change.
+- **Open 2026-09-30:** Elite sync cron re-enabled locally in `worker/schedules/cron.worker.sync.json` — pending deploy. RMA return receipts are not imported (Docking 1 below NetSuite).
+
 - **⚠ OPEN, unrelated: `GET /v2/notes/{uuid}/files` returns 405 `EV-7`** ("method not allowed /
   route does not exist") repeatedly for Elite. Found while diagnosing the 2026-09-08 transfer-order
   incident; it is **not** part of it. It does **not** abort the sync, and it was still occurring
@@ -450,6 +462,7 @@ Elite's PO backfill just did. **NOT FIXED** (shared file, 22 clients). Full root
   rewinding `NETSUITE_LAST_SYNC_DATETIME_SALES_ORDERS`.
 
 ## Change history
+- 2026-09-30 — Elite-only scope flags (owned-warehouse receipts, NS line location, skip TOs from unknown warehouse); NS 196 marked owned; receipt/SO data fixes; 7 closed-order shipments backfilled. (rgirish)
 - 2026-09-24 — TO↔PO links now via the two-direction reconcile; some upstream rows were vendor POs; SO downstream line links were being deleted on every PO re-sync (55 of 97 SO-linked vendor POs had none) — fixed. (jcardinal)
 - 2026-09-18 — **Stale-SalesOrder backfill is live: 218 → 187.** The retirement method needed
   four more FK dependencies before it would run (fulfillment **header** `salesOrderId`, the

package/package.json

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