toga-ai 1.0.827 → 1.0.828

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

@@ -6,7 +6,7 @@ project: Library
 client: nychh
 type: client-feature
 status: active
-updated: 2026-09-14
+updated: 2026-09-16
 owners: [jcardinal, bala, rgirish]
 files:
   - library/app/api/toga2.php
@@ -15,11 +15,11 @@ files:
   - worker/crons/toga2/netsuite/sync_togasupply_hh.php
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
   - worker/crons/toga2/netsuite/diagnose_hh_stuck_transfer_order.php
+  - worker/crons/toga2/netsuite/probe_import_single_order_hh.php
+  - worker/crons/toga2/netsuite/relink_transfer_order_pos_hh.php
   - dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql
   - dbchanges2/Client/2026-08-28a - TransferOrderItemsTimestampColumns.sql
-  - dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestampColumnsReposition.sql
-  - dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql
-  - dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.sql
+  - dbchanges2/Client_Nychh/2026-09-16a - TransferOrderBridgeAcl.sql
 related:
   - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
   - ../../../1.0/apps/library/features/toga2-api-client-and-bridge.md
@@ -92,6 +92,80 @@ sales-order linker. See the shared
 [SO↔PO bridge direction](../../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md)
 doc for the bridge naming convention.
 
+### ⚠ The bridge links were never being created — three stacked causes, fixed + prod-verified 2026-09-16
+
+The PO↔TO bridge links (header **and** line) were silently never forming for NYCHH. Three
+independent faults, peeled in order; the last was the real blocker:
+
+1. **Linking only ever ran from the `PURCHASE_ORDERS` section, which never runs for NYCHH.** The
+   links depended on the PO section, so a transfer-order import created none. **Fix:** a new **public**
+   `App_Api_Toga2::linkTransferOrderPurchaseOrders()` now runs on **every** transfer-order
+   import/retry from inside `syncTransferOrderFromNetsuite()`. It is **idempotent** — re-running an
+   import repairs any missing link. In `TRANSFER_ORDER_DETECTION_MODE__STOCKING_FLAG` mode it finds
+   the customer PO by the NetSuite **PO #** (`otherRefNum`, split on `' + '`) under the
+   `clientConfiguration['importCustomerPurchaseOrdersOnVendor']` vendor (the synthetic **Agilant**
+   vendor), then calls `linkPurchaseOrderToTransferOrder` for the header
+   (`PurchaseOrders_TransferOrders`) and line (`PurchaseOrderItems_TransferOrderItems`) links.
+2. **`linkPurchaseOrderToTransferOrder` read the TO line items from the wrong place, so line links
+   never formed.** It read `$transferOrder->transferOrderItems`, but **api2 NEVER inlines that
+   collection at any depth** (`transfer-orders` has no `InherentRecordChildren` row — same root cause
+   as the idempotency bug), so it was always empty. **Fix:** read TO items via
+   `getTransferOrderItemsByUuid` (the reliable direct `GET /transfer-order-items` query). Also lowered
+   the TO existence GET to `depth=1` and added `recordsPerPage=1000` to the PO-items GET.
+3. **ROOT CAUSE — an ACL gap, not code.** The NYCHH **API** role had **no write ACL** on the two
+   bridge records **325** (`PurchaseOrders_TransferOrders`) and **329**
+   (`PurchaseOrderItems_TransferOrderItems`), so the link POST failed api2 **EZ-3 / WZ-2** ("no
+   fields in which you are authorized to write"). The working **sales-order** bridge (record **276**,
+   `PurchaseOrders_SalesOrders`) already had the grant, which is why SO links worked and TO links did
+   not. **Also key: on CREATE, api2 `isPermitted()` DENIES a record permission that has no
+   `AclLogicGroups` chain — a bare `AclRecordPermissions` row is inert** (the standard four-table
+   chain rule — see [ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md)).
+
+**Fix migration:** `dbchanges2/Client_Nychh/2026-09-16a - TransferOrderBridgeAcl.sql` seeds the full
+four-table chain (`AclRecordExpressions` `'all'` → `AclRecordPermissions` full CRUD → `AclLogicGroups`
+AND → `AclLogicGroupExpressions`) **plus** `AclFieldPermissions isWritable = 1`, for roles **Base**
+and **API**, on records **325** and **329**, mirroring the working record 276. Guarded/re-runnable,
+roles resolved by name, fresh random v4 uuids, `Core` ids hardcoded (no `Client_*`→`Core` JOIN — the
+cross-cluster rule). The only writable fields a bridge POST touches are the row `uuid` + the two FK
+columns. **Data facts:** Core bridge record ids **276**=`PurchaseOrders_SalesOrders`,
+**325**=`PurchaseOrders_TransferOrders`, **329**=`PurchaseOrderItems_TransferOrderItems`; Core
+`RecordFields` **2210**=uuid/**2211**=purchaseOrderId/**2212**=transferOrderId (rec 325),
+**2226**=uuid/**2227**=purchaseOrderItemId/**2228**=transferOrderItemId (rec 329); `Client_Nychh`
+roles **1**=Base, **2**=Developer, **3**=API, **4**=Public. Reviews: `cto` AGREE (four-table chain),
+`sql-reviewer` SAFE TO MERGE.
+
+**ACL failures are now LOUD in the linker.** Both bridge existence checks **THROW** when their GET
+returns no `meta->totalRecordCount` (an ACL **read** gap) instead of silently skipping the create;
+the create POST already throws on a write-fail (EZ-3/WZ-2). So any future ACL gap stops the run
+rather than quietly producing zero links.
+
+**Verified in prod:** link `PurchaseOrderItems.id = 589` ↔ `TransferOrderItems.id = 7155` created for
+PO **EIT0012548** ↔ TO **284624** (NetSuite SO **7326440**).
+
+### PO discovery for a NYCHH transfer order — `otherRefNum` + Agilant vendor, NEVER `createdPo`
+
+For NYCHH the SO **line-level `createdPo` is NULL**; the PurchaseOrder is the **customer PO**
+(`otherRefNum`, the NetSuite "PO #" field) imported against the synthetic **Agilant** vendor. So PO
+discovery from a transfer order must use `otherRefNum` + the Agilant vendor — never `createdPo`.
+NetSuite proof: SO **7326440** `tranid` 284624, `otherrefnum` EIT0012548; its lines' `createdpo` are
+all null; in NetSuite it links only to an invoice + item fulfillment (there is **no** PurchaseOrder
+record on the SO itself).
+
+### Operator tools for this path (manual CLI, NOT scheduled)
+
+- **`worker/crons/toga2/netsuite/probe_import_single_order_hh.php`** — imports/relinks **one**
+  NetSuite order by internal id for NYCHH. Builds lookups by requiring `common_sync_togasupply.php`
+  with all `IS_ENABLED_INTEGRATION_*` false, fetches via `fetchSalesOrderByIdFull`, routes via
+  `isTransferOrder`, runs `syncTransferOrderFromNetsuite`, then prints diagnostics (`[diag]` PO
+  lookup, `[trace]` header-link POST response) and verifies header + line links. No cursor writes /
+  no process lock.
+- **`worker/crons/toga2/netsuite/relink_transfer_order_pos_hh.php`** — backfills links for **all**
+  existing `Client_Nychh` transfer orders. Pages every `TransferOrders` row, fetches each NetSuite
+  order for its PO #, runs only the link step (`App_Api_Toga2::linkTransferOrderPurchaseOrders` — no
+  re-import), idempotent, per-order `try/catch` that logs + collects failures (a sanctioned
+  operator-tool exception to fail-loud), with a live progress bar + counts + end summary. Optional
+  first arg = limit.
+
 ## Transfer-order origin/destination location resolution
 
 `TransferOrders.originLocationId` is **NOT NULL**, so a missing origin fails the V2 insert with
@@ -384,6 +458,25 @@ item receipts replays about two years unless it is rewound forward first.
 
 ## Change history
 
+- 2026-09-16 - **RESOLVED: the PO↔TO bridge links were never being created** (fixed end-to-end,
+  prod-verified: PO EIT0012548 ↔ TO 284624 / SO 7326440, link `PurchaseOrderItems.id=589` ↔
+  `TransferOrderItems.id=7155`). Three stacked causes: (1) linking only ran from the `PURCHASE_ORDERS`
+  section, which never runs for NYCHH → new **public** `linkTransferOrderPurchaseOrders()` now runs on
+  every TO import/retry, idempotent, finds the customer PO by `otherRefNum` (split on `' + '`) on the
+  Agilant vendor (`clientConfiguration['importCustomerPurchaseOrdersOnVendor']`); (2)
+  `linkPurchaseOrderToTransferOrder` read TO items from `$transferOrder->transferOrderItems`, which
+  api2 NEVER inlines → now reads via `getTransferOrderItemsByUuid` (also lowered the TO GET to depth 1,
+  added `recordsPerPage=1000` to the PO-items GET); (3) **ROOT CAUSE** — the NYCHH API role had no
+  write ACL on bridge records **325** (`PurchaseOrders_TransferOrders`) / **329**
+  (`PurchaseOrderItems_TransferOrderItems`), so the POST failed **EZ-3/WZ-2**; the working SO bridge
+  (rec 276) had it. Fix migration `dbchanges2/Client_Nychh/2026-09-16a - TransferOrderBridgeAcl.sql`
+  seeds the full four-table chain + `AclFieldPermissions` for roles Base + API on 325/329, mirroring
+  276 (guarded, roles by name, random v4 uuids, Core ids hardcoded). Also made ACL failures loud in
+  the linker (both existence GETs THROW on no `totalRecordCount`). Recorded the NYCHH PO data model:
+  `createdPo` is NULL, the PO is the customer PO (`otherRefNum`) on the Agilant vendor. Added two
+  manual operator tools (`probe_import_single_order_hh.php`, `relink_transfer_order_pos_hh.php`).
+  `cto` AGREE, `sql-reviewer` SAFE TO MERGE. **Deploy: library + worker together (via a WORKER
+  deploy — the worker box runs its own `/var/www/library` clone).** (jcardinal)
 - 2026-09-14 - **RESOLVED: the INVENTORY_ADJUSTMENTS destination wedge.** Root cause (prod): TO 277871
   (SO 7102750) has customer **3997 "1896 Laurel Hill Management, LLC"** — not a NYCHH customer and with
   **no `Client_Nychh.Locations` row**, so the destination never resolved and the NOT NULL insert 1048'd

package/package.json

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