toga-ai 1.0.767 → 1.0.768

package/knowledge/1.0/apps/library/features/netsuite-suiteql-rest-shim.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-09-03
-owners: [dfranks, jcardinal, kyalamarthi]
+owners: [dfranks, jcardinal, kyalamarthi, rgirish]
 files:
   - library/app/api/netsuite/rest.php
   - library/app/netsuite.php
@@ -78,6 +78,22 @@ Forecast2 tables already store.
   a per-type factor (it double-negates reversals back to positive). The shim flips
   `amount = -foreignamount`, `costEstimate = -costestimate`.
 
+- **⚠ `->holdInvoice` on a sales-order shim is NOT a native NetSuite field — it is normalised from
+  the custom checkbox `custbody_asi_hold` (internal id 4082), and that field is SHARED by all
+  clients.** NetSuite REST exposes no top-level `holdInvoice`. The `"asi"` prefix is **Agilant
+  Solutions Inc** (the company), *not* a client prefix — do not read it as client-specific. The read
+  lives **inside the shim**, in all three fetch paths: `buildSalesOrderShims()` (~L533, feeding both
+  `listSalesOrders()` and `fetchSalesOrderByIdFull()`) and `fetchSalesOrderById()` (~L1537), so
+  callers such as `App_Api_Toga2::isTransferOrder()` read an already-normalised boolean. (An earlier
+  version read `$nsOrder->holdInvoice` in the caller with a `custbody_hold_invoice` fallback — the
+  wrong field name; commit `07c31e24`, 2026-08-19, found the real one and moved the read down here.)
+  `worker/crons/toga2/compass/edi/2_create_so_netsuite.php` **writes** the same field.
+  **⚠ The SOAP client `library/app/netsuite.php` never sets `holdInvoice` at all**, so any detection
+  that depends on it (e.g. the `zero_dollar_hold` transfer-order mode — see
+  [per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md)) is **silently
+  always-false** on a SOAP path. Verified not a live risk: the togasupply engine calls
+  `App_Api_Netsuite_Rest::` on every sales-order/receipt/fulfillment path.
+
 - **`createdFrom` is not a usable SuiteQL column.** `transaction.createdfrom` is **always NULL**
   in SuiteQL (26/26). It is recoverable from `previoustransactionlinelink.previousdoc` excluding
   `previoustype = 'Opprtnty'` (an invoice links to both its SO and its opportunity; REST's
@@ -307,6 +323,16 @@ None — uniform across clients (NetSuite is a single shared account).
 
 ## Change history
 
+- 2026-09-03 — Documented that a sales-order shim's **`->holdInvoice` is not a native NetSuite
+  field**: it is normalised inside the shim from the custom checkbox **`custbody_asi_hold` (id
+  4082)**, which is **shared across all clients** ("asi" = Agilant Solutions Inc, not a client
+  prefix). Set in all three fetch paths (`buildSalesOrderShims()` feeding `listSalesOrders()` /
+  `fetchSalesOrderByIdFull()`, plus `fetchSalesOrderById()`); traced to commit `07c31e24`
+  (2026-08-19), which corrected the earlier caller-side read of `custbody_hold_invoice`. Recorded the
+  trap that the **SOAP client `app/netsuite.php` never sets it**, so hold-based detection is silently
+  always-false there — verified harmless today because the togasupply engine is REST-only.
+  Read-only session; no change to `rest.php`. (rgirish)
+
 - 2026-09-03 — Recorded that **`fetchItemFulfillmentById` and `fetchInventoryAdjustmentById` omitted
   `->lastModifiedDate`** (unlike `fetchItemReceiptById`), which froze ITEM_FULFILLMENTS + INVENTORY_ADJUSTMENTS
   once the 2026-09-02 per-record cursor read that field off the by-reference record these shims replace. GroWrk

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

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-09-03
-owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla"]
+owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
   - worker/crons/toga2/netsuite/sync_togasupply_canon.php
@@ -463,29 +463,71 @@ the code deploy).
 
 ## Client variations
 
-- **Transfer-order routing is opt-in per wrapper (default OFF).** A client whose NetSuite
-  *transfer orders* arrive as NetSuite *sales orders* can have the importer split them into
-  `TransferOrders` vs `SalesOrders` by setting
-  `const IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING = true;` before the `require_once`
-  (NYCHH's `sync_togasupply_hh.php` is the only one that does). The signal is the NetSuite custom
-  checkbox `custbody_stocking_order`, read by `App_Api_Toga2::isTransferOrder()`/`isStockingOrder()`
-  — **not** a dollar/hold heuristic. Full mechanics, PO bridges, and origin-location resolution:
-  [NYCHH NetSuite → TransferOrders import](../../../clients/nychh/features/netsuite-transfer-order-import.md).
-- **Transfer-order integration is governed by TWO DISTINCT wrapper flags — a master enable switch and a
-  NYCHH-only classification-mode switch (do not conflate them).**
+- **Transfer-order integration is governed by TWO DISTINCT wrapper constants — a master enable switch
+  and an explicit per-client detection MODE (do not conflate them).** These orders **masquerade as
+  NetSuite sales orders** and are split into `TransferOrders` vs `SalesOrders` by
+  `App_Api_Toga2::isTransferOrder()`.
   - **`IS_ENABLED_INTEGRATION_TRANSFER_ORDERS`** — the master "do transfer-order integration at all"
-    switch, defined in every `sync_togasupply_*.php` launcher. `true` for **GroWrk, Adyen, Elite, and
-    NYCHH**; `false` for the rest. These are the clients exercised by the shared
-    `syncTransferOrderFromNetsuite` / `getTransferOrderItemsByUuid` fixes (2026-08-30 above).
-  - **`IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING`** — a **separate classification-mode** switch,
-    **NYCHH-only** (`sync_togasupply_hh.php`), that makes `App_Api_Toga2::isTransferOrder()` classify by
-    the NetSuite `custbody_stocking_order` checkbox instead of the legacy rule.
-
-  These orders **masquerade as NetSuite sales orders** and are split into `TransferOrders` vs
-  `SalesOrders` by `isTransferOrder()`. The classification **SIGNAL is per-client**: **NYCHH** routes by
-  the `custbody_stocking_order` stocking flag (above); **GroWrk / Elite / Adyen** use the **legacy rule**
-  (`holdInvoice AND total === 0`). Do **not** assume one universal signal — the master enable is shared,
-  the classification mode is not.
+    switch, defined in every `sync_togasupply_*.php` launcher. `true` for **GroWrk, Adyen, and
+    NYCHH**; `false` for Elite (pre-wired, not on) and the rest. **Every one of the 7
+    `isTransferOrder()` call sites is guarded by this**, so the mode throw below can never fire for a
+    client with transfer orders off.
+  - **`TRANSFER_ORDER_DETECTION_MODE`** — the classification mode, one of two `App_Api_Toga2` class
+    constants (see next bullet). Required whenever the master switch is on.
+
+### ⚠ `TRANSFER_ORDER_DETECTION_MODE` — explicit per client, NO default, throws if unset (2026-09-03)
+
+`isTransferOrder()` used to branch on a boolean `IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING`
+(defined only in NYCHH's launcher) and **otherwise fall through to GroWrk's legacy `$0 total +
+holdInvoice` rule**. That made the legacy rule an **implicit, silent default**: a new client turning
+transfer orders on without the constant silently got another client's classification applied to its
+orders, on a green-looking run. That boolean is **removed everywhere**.
+
+Each launcher now declares an explicit mode before its `require_once`:
+
+```php
+const TRANSFER_ORDER_DETECTION_MODE = App_Api_Toga2::TRANSFER_ORDER_DETECTION_MODE__STOCKING_FLAG;
+// or
+const TRANSFER_ORDER_DETECTION_MODE = App_Api_Toga2::TRANSFER_ORDER_DETECTION_MODE__ZERO_DOLLAR_HOLD;
+```
+
+| Mode constant | Value | Rule | Clients |
+|---|---|---|---|
+| `TRANSFER_ORDER_DETECTION_MODE__STOCKING_FLAG` | `'stocking_flag'` | NetSuite checkbox `custbody_stocking_order` (id 7097) — **unchecked = transfer order** | NYCHH |
+| `TRANSFER_ORDER_DETECTION_MODE__ZERO_DOLLAR_HOLD` | `'zero_dollar_hold'` | `holdInvoice === true` **AND** `total === 0` | GroWrk, Adyen, Elite (pre-set, unused — its master switch is off) |
+
+`App_Api_Toga2::TRANSFER_ORDER_DETECTION_MODES` is the allowlist array. **`isTransferOrder()` THROWS
+when the mode is undefined or not in the allowlist** — a deliberate fail-loud, chosen over defaulting
+to the legacy rule, consistent with the 2026-08-27 "every section fails loud" policy. Consequence,
+and it is not optional: **`library` and `worker` MUST deploy together.** A worker deploy without the
+library (or vice versa) crashes GroWrk and Adyen on their next sync run.
+
+- **A separate NYCHH-only flag, `IS_ENABLED_INVENTORY_ADJUSTMENT_FULFILLMENT_LINK`,** now guards
+  `attachInventoryAdjustmentToItemFulfillment()` (the `custbody_stock_adjustment` link). The removed
+  routing boolean had been doing double duty for it; it is an unrelated feature that merely has NYCHH
+  as its only client today. See
+  [NYCHH inventory-adjustment → item-fulfillment linking](../../../clients/nychh/features/netsuite-inventory-adjustment-fulfillment-link.md).
+
+- **`->holdInvoice` is NOT a native NetSuite field** — it is normalised by the REST shim from the
+  custom checkbox `custbody_asi_hold` (internal id **4082**), which is **shared across all clients**
+  ("asi" = Agilant Solutions Inc, the company, not a client prefix). `App_Api_Netsuite_Rest` sets it
+  in `buildSalesOrderShims()` (feeding `listSalesOrders()` + `fetchSalesOrderByIdFull()`) and in
+  `fetchSalesOrderById()`. **`app/netsuite.php` (SOAP) never sets it at all** — ZERO_DOLLAR_HOLD would
+  be silently always-false on a SOAP path. Not a live risk: `common_sync_togasupply.php` uses
+  `App_Api_Netsuite_Rest::` on **every** sales-order / receipt / fulfillment path, and all
+  transfer-order clients are on REST. Field detail:
+  [SuiteQL/REST shim](../../library/features/netsuite-suiteql-rest-shim.md).
+
+- **⚠ OPEN (pre-existing, not fixed): an absent NetSuite `total` collapses to `0.0` and can
+  misclassify.** The ZERO_DOLLAR_HOLD branch reads
+  `$total = isset($nsOrder->total) ? (float) $nsOrder->total : 0.0;`. A REST response with a
+  missing/blank `total` (transient API failure — not a real $0 order) becomes `0.0`, and combined with
+  the hold flag set, a **non-zero order classifies as a transfer order**. This line predates the mode
+  refactor and was carried across unchanged; it goes against the fail-loud rule for cron/sync code.
+  Raised with the developer, left as-is pending a decision.
+- **Full mechanics of the stocking-flag mode** (PO bridges, origin-location resolution):
+  [NYCHH NetSuite → TransferOrders import](../../../clients/nychh/features/netsuite-transfer-order-import.md).
+  Legacy-rule background: [GroWrk transfer order flow](../../../clients/growrk/features/transfer-order-flow.md).
 - `isParentCustomer` — `true` walks NetSuite child customers (`listChildCustomers`); `false`
   syncs the single customer. Prudential-EDI and the live Quad wrapper use `false`.
 - The original combined-array entries used `App_Api_Toga2::CLIENT_UUID_*` consts for Quad and
@@ -1212,6 +1254,23 @@ the code deploy).
 
 ## Change history
 
+- 2026-09-03 — **Transfer-order detection is now an explicit per-client MODE with no default; the old
+  `IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING` boolean is removed from both repos.**
+  `isTransferOrder()` previously branched on that boolean (NYCHH-only) and otherwise fell through to
+  GroWrk's `$0 total + holdInvoice` rule — an implicit silent default that would apply one client's
+  classification to another's orders on a green-looking run. Launchers now set
+  `TRANSFER_ORDER_DETECTION_MODE` to one of two new `App_Api_Toga2` constants
+  (`__STOCKING_FLAG` = NYCHH, `__ZERO_DOLLAR_HOLD` = GroWrk/Adyen/Elite), validated against a
+  `TRANSFER_ORDER_DETECTION_MODES` allowlist; an undefined/unknown mode **throws**. All 7 call sites
+  are guarded by `IS_ENABLED_INTEGRATION_TRANSFER_ORDERS`, so the throw can't fire for a client with
+  TOs off. The `custbody_stock_adjustment` adjustment→fulfillment link, which the removed boolean was
+  also guarding, moved to its own `IS_ENABLED_INVENTORY_ADJUSTMENT_FULFILLMENT_LINK` (NYCHH only).
+  Also recorded: `->holdInvoice` is the REST shim's normalisation of the **shared** custom checkbox
+  `custbody_asi_hold` (id 4082, "asi" = Agilant Solutions Inc, not a client), never set on the SOAP
+  path — safe today because this engine is REST-only; and the pre-existing `total ?: 0.0` default in
+  the ZERO_DOLLAR_HOLD branch can misclassify on a transient NetSuite failure (open, unchanged).
+  **`library` + `worker` must deploy together** or GroWrk and Adyen throw on their next run. (rgirish)
+
 - 2026-09-03 — **By-reference shim wrote the cursor on the WRONG CLOCK → ITEM_RECEIPTS + ITEM_FULFILLMENTS
   re-matched the same record forever (fixed, `library` only).** Follow-on to the same-day by-reference
   fix below: the shims set `lastModifiedDate` from the REST GET (UTC), `date()`-formatted in

package/knowledge/INDEX.md

@@ -45,6 +45,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## Clients
 
+- **Adyen** (`adyen`) → [clients/adyen/INDEX.md](clients/adyen/INDEX.md)
 - **AIG (Staples Protection Plan)** (`aig`) → [clients/aig/INDEX.md](clients/aig/INDEX.md)
 - **Canon** (`canon`) → [clients/canon/INDEX.md](clients/canon/INDEX.md)
 - **Compass Canada** (`compass-canada`) → [clients/compass-canada/INDEX.md](clients/compass-canada/INDEX.md)

package/knowledge/clients/adyen/INDEX.md

@@ -0,0 +1,5 @@
+# Client: Adyen `adyen`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Adyen](profile.md) | 2.0 | Adyen is a live TOGa Supply client (`Client_Adyen` database) on the shared **NetSuite → TOGa Supply** importer, with its own 1.0 launcher `worker/crons/toga2/ne | worker/crons/toga2/netsuite/sync_togasupply_adyen.php, library/app/api/toga2.php |

package/knowledge/clients/adyen/profile.md

@@ -0,0 +1,59 @@
+---
+title: Adyen
+framework: "2.0"
+apps:
+  - worker
+  - library
+  - _underscore
+  - api2
+  - dbchanges2
+project: Worker
+client: adyen
+type: profile
+status: draft
+updated: 2026-09-03
+owners: ["rgirish"]
+files:
+  - worker/crons/toga2/netsuite/sync_togasupply_adyen.php
+  - library/app/api/toga2.php
+related:
+  - ../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
+  - ../growrk/features/transfer-order-flow.md
+  - ../../2.0/apps/_underscore/features/acl-permission-chain.md
+---
+
+## Summary
+
+Adyen is a live TOGa Supply client (`Client_Adyen` database) on the shared **NetSuite → TOGa Supply**
+importer, with its own 1.0 launcher `worker/crons/toga2/netsuite/sync_togasupply_adyen.php`.
+
+**This profile was created as a stub (2026-09-03).** Adyen had no `clients/` folder despite being a
+live, scheduled client — it surfaced while refactoring transfer-order detection, because Adyen is one
+of the clients whose launcher carries `IS_ENABLED_INTEGRATION_TRANSFER_ORDERS = true`. It is
+deliberately marked `status: draft`: the entries below are what is verifiable from code and existing
+docs, not a curated client picture. **Anyone doing Adyen work should flesh this out.** Whether Adyen
+was previously undocumented intentionally has not been confirmed.
+
+## What is known
+
+- **NetSuite → TOGa Supply sync.** A per-client thin wrapper over the shared engine — full mechanics
+  on [per-client sync](../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
+- **Transfer orders are ENABLED** (`IS_ENABLED_INTEGRATION_TRANSFER_ORDERS = true`). Adyen's NetSuite
+  transfer orders arrive **as NetSuite sales orders** and are classified by the
+  `TRANSFER_ORDER_DETECTION_MODE__ZERO_DOLLAR_HOLD` mode — `holdInvoice === true` **AND**
+  `total === 0`, the same rule as GroWrk (see
+  [GroWrk transfer order flow](../growrk/features/transfer-order-flow.md)). This mode is now declared
+  explicitly in Adyen's launcher; `App_Api_Toga2::isTransferOrder()` throws if it is missing, so
+  **`library` and `worker` must deploy together** for Adyen.
+  - ⚠ **Not independently verified against Adyen's NetSuite account.** The mode preserves the
+    behavior Adyen had under the old implicit default; nobody has confirmed with the client that $0 +
+    hold is the right signal *for Adyen*. Worth checking before trusting the split.
+- **`Client_Adyen` is one of the client DBs with surface-layer / ACL drift** noted on the
+  [ACL permission chain](../../2.0/apps/_underscore/features/acl-permission-chain.md) and
+  [surface-layer schema](../../2.0/apps/dbchanges2/features/surface-layer-schema.md) docs.
+
+## Open questions
+
+- Formal/legal client name and account owner — recorded here simply as **Adyen**.
+- Which repos beyond the `apps:` list above are genuinely in Adyen's scope.
+- Whether Adyen has client-specific models/features that deserve their own docs.

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

@@ -6,8 +6,8 @@ project: Worker
 client: elite
 type: client-feature
 status: active
-updated: 2026-09-02
-owners: ["snaredla", "jcardinal"]
+updated: 2026-09-03
+owners: ["snaredla", "jcardinal", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/sync_togasupply_elite.php
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -88,6 +88,13 @@ the trait declares must exist as a column, a `CustomRecordFields` row **and** an
   so it always trails.)
 - **`MIN_DATETIME_TO_CHECK_FOR_NETSUITE_DATA = '2018-01-01'`**, with the real start controlled by the
   seeded `Parameters` cursors.
+- **`TRANSFER_ORDER_DETECTION_MODE` is pre-set but NOT in use (2026-09-03).** Elite's wrapper declares
+  `App_Api_Toga2::TRANSFER_ORDER_DETECTION_MODE__ZERO_DOLLAR_HOLD` (`holdInvoice && total === 0`, the
+  GroWrk rule) so that the constant exists if transfer orders are ever switched on — but Elite's
+  master switch `IS_ENABLED_INTEGRATION_TRANSFER_ORDERS` is **`false`**, so `isTransferOrder()` is
+  never reached today. Before flipping the master switch, confirm Elite's NetSuite actually represents
+  transfer orders as $0 held sales orders; do not assume the pre-set mode is correct for them. Mode
+  mechanics: [per-client sync](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
 
 ## Gotchas / known issues
 
@@ -125,6 +132,13 @@ the trait declares must exist as a column, a `CustomRecordFields` row **and** an
 
 ## Change history
 
+- 2026-09-03 — Elite's wrapper now declares `TRANSFER_ORDER_DETECTION_MODE =
+  App_Api_Toga2::TRANSFER_ORDER_DETECTION_MODE__ZERO_DOLLAR_HOLD` as part of the shared
+  transfer-order detection-mode refactor (the old `IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING`
+  boolean was removed and there is no longer a default mode). **Dormant for Elite** —
+  `IS_ENABLED_INTEGRATION_TRANSFER_ORDERS` is `false`, so `isTransferOrder()` is never reached; verify
+  the rule against Elite's NetSuite before enabling. (rgirish)
+
 - 2026-09-02 — **Elite PURCHASE_ORDERS froze on a dropped PO line that still had a receipt** (shared
   fix, `library` only — now DEPLOYED to `_production`, PO import confirmed unfrozen on Elite). Elite was
   the confirmed prod case: `NETSUITE_EXECUTION_MODE_PURCHASE_ORDERS='1-RUNNING'`, watermark frozen at **2025-10-13**,

package/knowledge/clients/growrk/INDEX.md

@@ -3,6 +3,6 @@
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
 | [GroWrk — shipping-carrier cleanup, UPS visibility, and the NetSuite Fulfill-and-Ship punch-out URL](features/shipping-carrier-cleanup.md) | 2.0 | GroWrk (`Core.Clients` id **33**, DB `Client_Growrk`) is where the runaway `ShippingCarriers` duplication was found and fixed (TRUE-81576). | _underscore/Trait/Netsuite/SalesOrder.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts |
-| [Transfer Order Flow (NetSuite SalesOrder workaround → dedicated TransferOrders)](features/transfer-order-flow.md) | 2.0 | GroWrk moves inventory between their own locations (warehouses, distribution points). | _underscore/Model/Client/TransferOrder.php, _underscore/Model/Client/TransferOrderItem.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemReceipt.php, _underscore/Model/Client/ItemReceiptItem.php, _underscore/Trait/Netsuite/TransferOrder.php, dbchanges2/Client_Growrk/, dbchanges2/Client/ |
+| [Transfer Order Flow (NetSuite SalesOrder workaround → dedicated TransferOrders)](features/transfer-order-flow.md) | 2.0 | GroWrk moves inventory between their own locations (warehouses, distribution points). | _underscore/Model/Client/TransferOrder.php, _underscore/Model/Client/TransferOrderItem.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemReceipt.php, _underscore/Model/Client/ItemReceiptItem.php, _underscore/Trait/Netsuite/TransferOrder.php, dbchanges2/Client_Growrk/, dbchanges2/Client/, worker/crons/toga2/netsuite/sync_togasupply_growrk.php, library/app/api/toga2.php |
 | [GroWrk NetSuite-module custom fields — the never-executed 2026-05-28 commit (Units + ServiceRequests 500s)](features/units-netsuite-custom-fields.md) | 2.0 | GroWrk is on the dbchanges2 **`netsuite`** module (`dbchanges2/Client_Growrk/_modules.txt`), so its Units carry the module's seven `c_` custom fields. | _underscore/Trait/Netsuite/Unit.php, _underscore/Model/Growrk/Unit.php, _underscore/Model/Growrk/ItemFulfillment.php, dbchanges2/Client_Growrk/2026-05-28.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/2026-08-10c - GrowrkServiceRequestCustomFieldsCatchUp.sql, dbchanges2/Client_Growrk/2026-08-10d - GrowrkServiceRequestTypeAndDispositionSeeds.sql, dbchanges2/Client_Growrk/_modules.txt |
 | [GroWrk](profile.md) | 2.0 | GroWrk is a 2.0 client using TOGA for inventory and order management. |  |

package/knowledge/clients/growrk/features/transfer-order-flow.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: growrk
 type: client-feature
 status: active
-updated: 2026-06-19
+updated: 2026-09-03
 owners: ["rgirish"]
 files:
   - _underscore/Model/Client/TransferOrder.php
@@ -17,9 +17,14 @@ files:
   - _underscore/Trait/Netsuite/TransferOrder.php
   - dbchanges2/Client_Growrk/
   - dbchanges2/Client/
+  - worker/crons/toga2/netsuite/sync_togasupply_growrk.php
+  - library/app/api/toga2.php
 related:
   - 2.0/apps/_underscore/features/recursive-item-fulfillments.md
   - 2.0/apps/worker2/architecture.md
+  - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
+  - ../../../1.0/apps/library/features/netsuite-suiteql-rest-shim.md
+  - ../../nychh/features/netsuite-transfer-order-import.md
 ---
 
 ## Summary
@@ -40,8 +45,28 @@ GroWrk moves inventory between their own locations (warehouses, distribution poi
 
 ## How it works
 
-### Identification signal
-A NetSuite SalesOrder is a TransferOrder if and only if: `holdInvoice === true` AND `total === 0`. Both conditions must hold — `holdInvoice` alone is not sufficient.
+### Identification signal — now a NAMED, EXPLICIT mode (2026-09-03)
+
+A NetSuite SalesOrder is a TransferOrder if and only if: `holdInvoice === true` **AND** `total === 0`.
+Both conditions must hold — `holdInvoice` alone is not sufficient.
+
+This rule is **GroWrk's**, not universal (NYCHH uses the `custbody_stocking_order` stocking flag), and
+it is no longer an implicit fallback. It is now the named mode
+`App_Api_Toga2::TRANSFER_ORDER_DETECTION_MODE__ZERO_DOLLAR_HOLD` (`'zero_dollar_hold'`), declared
+explicitly in GroWrk's 1.0 launcher `worker/crons/toga2/netsuite/sync_togasupply_growrk.php`:
+
+```php
+const TRANSFER_ORDER_DETECTION_MODE = App_Api_Toga2::TRANSFER_ORDER_DETECTION_MODE__ZERO_DOLLAR_HOLD;
+```
+
+`App_Api_Toga2::isTransferOrder()` **throws** if the mode is missing — so GroWrk's launcher and the
+library must deploy together. Adyen and Elite use the same mode. Full mechanics:
+[per-client sync — transfer-order detection mode](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
+
+**`holdInvoice` is not a native NetSuite field** — the REST shim normalises it from the custom
+checkbox `custbody_asi_hold` (id **4082**), which is shared by every client ("asi" = Agilant Solutions
+Inc, the company). The SOAP client never sets it. See the
+[SuiteQL/REST shim](../../../1.0/apps/library/features/netsuite-suiteql-rest-shim.md).
 
 ### Two-stage closure
 - **Outbound:** An `ItemFulfillment` with `transferOrderId` set (not `salesOrderId`) closes the outbound side — items leave the origin location.
@@ -113,7 +138,24 @@ Full plan saved at `/Applications/AMPPS/www/transfer-order-plan.md`.
 - **Lazy transaction gotcha.** `_Database::register()` auto-starts a lazy transaction since Apr 2026. The worker must call `_Database::transactionCommit(DB_CLIENT)` before any SQS dispatch or the TO insert rolls back silently.
 - **Bridge table scope confirmed as all-clients.** The 8 bridge tables go in `dbchanges2/Client/` (not `Client_Growrk/`). Schema fixes (dtCreated etc.) stay in `Client_Growrk/` — other clients don't need them.
 - **NS identification: both conditions required.** `holdInvoice=true` alone is not a safe signal — must also confirm `total === 0`.
+- **⚠ An ABSENT NetSuite `total` reads as `0.0` and can misclassify a real order (open, unfixed).**
+  The 1.0 detection branch does `$total = isset($nsOrder->total) ? (float) $nsOrder->total : 0.0;`, so
+  a NetSuite REST response with a missing/blank total — a transient API failure, not a genuine $0
+  order — collapses to `0.0`; combined with the hold flag set, a **non-zero order is classified as a
+  transfer order**. Pre-existing, carried unchanged through the 2026-09-03 mode refactor, and raised
+  with the developer. If you see an unexpected TransferOrder for GroWrk, check this first.
+- **The mode is now mandatory in the launcher.** Removing/forgetting
+  `TRANSFER_ORDER_DETECTION_MODE` in `sync_togasupply_growrk.php` makes `isTransferOrder()` **throw**
+  — GroWrk's sync will fail loud, by design, rather than silently reclassify.
 
 ## Change history
 
+- 2026-09-03 — GroWrk's `holdInvoice && total === 0` rule was **formalised as the named mode**
+  `App_Api_Toga2::TRANSFER_ORDER_DETECTION_MODE__ZERO_DOLLAR_HOLD`, declared explicitly in
+  `worker/crons/toga2/netsuite/sync_togasupply_growrk.php`. It had been the *implicit fallback* in
+  `isTransferOrder()`, which silently applied GroWrk's rule to any other client that enabled transfer
+  orders; there is now no default and an unset mode throws. Recorded that `holdInvoice` is the REST
+  shim's normalisation of the shared custom checkbox `custbody_asi_hold` (id 4082) and that the SOAP
+  client never sets it, plus the open `total ?: 0.0` misclassification risk. **library + worker must
+  deploy together** or GroWrk throws on its next sync run. (rgirish)
 - 2026-06-19 — Designed full transfer order flow; confirmed DB state in prod; produced 5-phase implementation plan pending team review (rgirish)

package/knowledge/clients/nychh/features/netsuite-inventory-adjustment-fulfillment-link.md

@@ -6,8 +6,8 @@ project: Library
 client: nychh
 type: client-feature
 status: active
-updated: 2026-09-01
-owners: [jcardinal]
+updated: 2026-09-03
+owners: [jcardinal, rgirish]
 files:
   - library/app/api/toga2.php
   - library/app/api/netsuite/rest.php
@@ -46,7 +46,13 @@ on-demand fulfillment/sales-order import it triggers — was **migrated from SOA
 
 Like [NYCHH transfer-order import](./netsuite-transfer-order-import.md), the FK columns and models
 are **all-client infrastructure** but the **attach is gated NYCHH-only** by
-`IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING`.
+`IS_ENABLED_INVENTORY_ADJUSTMENT_FULFILLMENT_LINK` (defined `true` in `sync_togasupply_hh.php`).
+
+> **Renamed 2026-09-03.** This used to piggyback on the transfer-order routing boolean
+> `IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING`, which was doing double duty. That constant is
+> gone; the adjustment→fulfillment link now has its **own** flag and is fully independent of
+> transfer-order detection (which is now a per-client *mode*, not a boolean — see
+> [per-client sync](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md)).
 
 ## The two FK links (replaced the header/line bridge tables)
 
@@ -63,7 +69,7 @@ link is now a plain PUT of the FK uuid onto the parent record, not a bridge-row
 ## Attach code — `App_Api_Toga2::attachInventoryAdjustmentToItemFulfillment`
 
 Lives in `library/app/api/toga2.php`, called from `syncInventoryAdjustmentFromNetsuite` **after the
-header upsert**, gated on `IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING`. It:
+header upsert**, gated on `IS_ENABLED_INVENTORY_ADJUSTMENT_FULFILLMENT_LINK`. It:
 
 1. reads `custbody_stock_adjustment` off the adjustment (the related Item Fulfillment),
 2. resolves that fulfillment by `ItemFulfillments.c_netsuiteInternalItemFulfillmentId`,
@@ -221,6 +227,11 @@ this feature on the scheduled cron.
 
 ## Change history
 
+- 2026-09-03 — **Gate flag split off onto its own constant.** The attach was guarded by the
+  transfer-order routing boolean `IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING`, which was doing
+  double duty; that constant was removed when transfer-order detection became a per-client *mode*.
+  The link is now gated by `IS_ENABLED_INVENTORY_ADJUSTMENT_FULFILLMENT_LINK` (NYCHH launcher only) —
+  same behavior, no longer coupled to routing. **library + worker deploy together.** (rgirish)
 - 2026-09-01 — **Unfroze NYCHH `INVENTORY_ADJUSTMENTS` — serial-CASE mismatch in the `/units` lookup
   (shared `library`, working-tree, not yet committed/deployed).** `syncInventoryAdjustmentFromNetsuite`
   keyed the units lookup by the returned serial (`'n/a'`) but probed with the uppercased NetSuite serial

package/knowledge/clients/nychh/features/netsuite-transfer-order-import.md

@@ -6,8 +6,8 @@ project: Library
 client: nychh
 type: client-feature
 status: active
-updated: 2026-09-02
-owners: [jcardinal, bala]
+updated: 2026-09-03
+owners: [jcardinal, bala, rgirish]
 files:
   - library/app/api/toga2.php
   - library/app/api/netsuite/rest.php
@@ -65,11 +65,16 @@ private `linkPurchaseOrderToTransferOrder()` mirrors the existing sales-order PO
 > [GroWrk transfer order flow](../../growrk/features/transfer-order-flow.md) — is client-specific and
 > not universal; the TO-detection signal must be read per client.)
 
-**Routing is opt-in per client, default OFF.** The shared engine only routes to TransferOrders when
-the wrapper enables it. NYCHH's wrapper sets
-`const IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING = true;` in
-`worker/crons/toga2/netsuite/sync_togasupply_hh.php`; every other client inherits the default (off)
-and behaves exactly as before.
+**Routing mode is declared per client — there is NO default (2026-09-03).** The old boolean
+`IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING` is **gone**. NYCHH's wrapper now sets
+
+```php
+const TRANSFER_ORDER_DETECTION_MODE = App_Api_Toga2::TRANSFER_ORDER_DETECTION_MODE__STOCKING_FLAG;
+```
+
+in `worker/crons/toga2/netsuite/sync_togasupply_hh.php`. `isTransferOrder()` **throws** if the mode
+is undefined or not in the `TRANSFER_ORDER_DETECTION_MODES` allowlist — see the shared
+[per-client sync — transfer-order detection mode](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
 
 ## PO ↔ order bridge links (header + line)
 
@@ -246,16 +251,29 @@ refused on the prod client cluster):
   broken.
 - **Order 128829 (no location anywhere) is unresolved** — see the origin-resolution section. Do not
   assume the importer is broken if this single order is stuck; every located order imports.
-- **Routing is gated by the wrapper constant.** If a future client should route transfer orders,
-  add `const IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING = true;` before its
-  `require_once 'common_sync_togasupply.php';` — and confirm that client actually sets
-  `custbody_stocking_order` in NetSuite. Absent the flag, everything lands in SalesOrders.
+- **Routing mode is declared by the wrapper and there is NO fallback.** If a future client should
+  route transfer orders by the stocking flag, add
+  `const TRANSFER_ORDER_DETECTION_MODE = App_Api_Toga2::TRANSFER_ORDER_DETECTION_MODE__STOCKING_FLAG;`
+  before its `require_once 'common_sync_togasupply.php';` — and confirm that client actually sets
+  `custbody_stocking_order` in NetSuite. Omitting the mode no longer lands everything in
+  SalesOrders; it **throws** (deliberate — see the shared engine doc).
+- **The `custbody_stock_adjustment` inventory-adjustment link is on its OWN flag now.**
+  `attachInventoryAdjustmentToItemFulfillment()` used to piggyback on the old routing boolean; it is
+  now gated by `IS_ENABLED_INVENTORY_ADJUSTMENT_FULFILLMENT_LINK` (NYCHH-only) — see
+  [NYCHH inventory-adjustment → item-fulfillment linking](./netsuite-inventory-adjustment-fulfillment-link.md).
 - **`custbody_stocking_order` must reach the shim.** `fetchSalesOrderById()` now carries the field
   via `customFieldList`; a missing custom field read returns null → the order routes as a transfer
   order (unchecked = transfer). Verify the field is populated in NetSuite before trusting the split.
 
 ## Change history
 
+- 2026-09-03 — **`IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING` removed.** NYCHH now declares
+  `const TRANSFER_ORDER_DETECTION_MODE = App_Api_Toga2::TRANSFER_ORDER_DETECTION_MODE__STOCKING_FLAG;`
+  in `sync_togasupply_hh.php`; `isTransferOrder()` throws on an undefined/unknown mode instead of
+  silently falling back to GroWrk's `$0 + hold` rule. The `custbody_stock_adjustment`
+  inventory-adjustment → item-fulfillment link, which the old boolean was also guarding, moved to its
+  own NYCHH-only `IS_ENABLED_INVENTORY_ADJUSTMENT_FULFILLMENT_LINK`. **library and worker must deploy
+  together.** (rgirish)
 - 2026-09-02 — Recorded **why** the importer can never resolve an origin from the NetSuite header:
   on a NYCHH transfer order the **destination** location is the NetSuite customer and the **origin**
   is the NetSuite warehouse, so `entity` is always the destination (verified in prod across all 1,930

package/package.json

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