toga-ai 1.0.707 → 1.0.708

package/knowledge/clients/nychh/INDEX.md

@@ -5,5 +5,5 @@
 | [NYCHH inventory-adjustment → item-fulfillment linking (direct FK columns, REST)](features/netsuite-inventory-adjustment-fulfillment-link.md) | 1.0 | For NYCHH stock adjustments, the NetSuite **inventory adjustment** carries a link to the **Item Fulfillment** it corrects, on the multi-select body custom field | library/app/api/toga2.php, library/app/api/netsuite/rest.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_hh.php, worker/crons/toga2/netsuite/diagnose_hh_import_inventory_adjustment.php |
 | [NYCHH NetSuite → TransferOrders import (stocking-flag routing, PO bridges, origin location)](features/netsuite-transfer-order-import.md) | 1.0 | NYCHH's NetSuite **transfer orders are represented as NetSuite sales orders** (same as the GroWrk pattern), so the shared NetSuite → TOGa Supply importer (`App_ | library/app/api/toga2.php, library/app/api/netsuite/rest.php, library/app/netsuite.php, 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, 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 |
 | [NYCHH PO links are UPSTREAM — the downstream SO→PO route returns empty](features/po-number-upstream-direction.md) | 2.0 | NYCHH's sales orders are created **from the customer's purchase order**, so their SO↔PO links live in the **upstream** table `PurchaseOrders_SalesOrders` (route | _underscore/Model/Client/SalesOrder.php, _underscore/Trait/Netsuite/SalesOrder.php, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts, dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql, dbchanges2/Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql |
-| [NYCHH transfer-order 2.0 model — inventory quantities + V2 field enablement](features/transfer-order-inventory-quantities.md) | 2.0 | The 2.0 (`_underscore`) side of NYCHH transfer-order support: a **two-branch inventory quantity model** on the NYCHH `Item` override, plus the **client-override | _underscore/Model/Nychh/Item.php, _underscore/Model/Nychh/TransferOrder.php, _underscore/Model/Nychh/TransferOrderStage.php, _underscore/Model/Client/TransferOrder.php, _underscore/Model/Client/TransferOrderItem.php, dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql, dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql |
+| [NYCHH transfer-order 2.0 model — inventory quantities + V2 field enablement](features/transfer-order-inventory-quantities.md) | 2.0 | The 2.0 (`_underscore`) side of NYCHH transfer-order support: a **two-branch inventory quantity model** on the NYCHH `Item` override, plus the **client-override | _underscore/Model/Nychh/Item.php, _underscore/Model/Nychh/PurchaseOrderItem.php, _underscore/Model/Nychh/TransferOrder.php, _underscore/Model/Nychh/TransferOrderStage.php, _underscore/Model/Client/TransferOrder.php, _underscore/Model/Client/TransferOrderItem.php, dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql, dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql |
 | [NYC Health & Hospitals](profile.md) | 2.0 | NYC Health & Hospitals (NYCHH) is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Nychh`. | dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql, dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql |

package/knowledge/clients/nychh/features/transfer-order-inventory-quantities.md

@@ -6,10 +6,11 @@ project: _Underscore
 client: nychh
 type: client-feature
 status: active
-updated: 2026-08-28
+updated: 2026-08-31
 owners: [jcardinal, apeterson]
 files:
   - _underscore/Model/Nychh/Item.php
+  - _underscore/Model/Nychh/PurchaseOrderItem.php
   - _underscore/Model/Nychh/TransferOrder.php
   - _underscore/Model/Nychh/TransferOrderStage.php
   - _underscore/Model/Client/TransferOrder.php
@@ -25,6 +26,8 @@ related:
   - ../../../2.0/apps/toga25-supply/features/transfer-orders-page.md
   - ../../growrk/features/transfer-order-flow.md
   - ./netsuite-transfer-order-import.md
+  - ./netsuite-inventory-adjustment-fulfillment-link.md
+  - ../../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md
   - ../profile.md
 ---
 
@@ -47,20 +50,84 @@ NYCHH-specific composition.
 
 ## NYCHH-only quantity calculations (two-branch inventory model)
 
-Per the 2026-08-17 "TOGa Supply" meeting. **NYCHH ONLY** — the overrides live on the client model
-`_Model_Nychh_Item` (`_underscore/Model/Nychh/Item.php`), not the base. Stocking orders bring stock
-**in**, transfer orders send it **out**, so the quantities reflect that direction:
+Per the 2026-08-17 and 2026-08-27 "TOGa Supply" meetings. **NYCHH ONLY** — the overrides live on the
+client models `_Model_Nychh_Item` (`_underscore/Model/Nychh/Item.php`) and, as of 2026-08-31, the new
+`_Model_Nychh_PurchaseOrderItem` (`_underscore/Model/Nychh/PurchaseOrderItem.php`), not the base.
+Stocking orders bring stock **in**, transfer orders send it **out**, so the quantities reflect that
+direction:
 
 | Quantity | Definition |
 |---|---|
-| **on hand** | `received` (PO item receipts) − `fulfilled` (transfer-order item fulfillments) |
+| **received** (stock-in) | net Σ `InventoryAdjustmentItems.quantityAdjustBy` on the item's **stocking** fulfillments |
+| **on hand** | `received` − `fulfilled` (transfer-order item fulfillments) |
 | **available** | `on hand` − `committed` |
 | **fulfilled** | Σ shipped transfer-order fulfillments |
-| **backordered** | `ordered` − `received` |
+| **backordered** | `ordered` − `received` (floored at 0) |
 
-`_qtyOnOrder` was added alongside these. The stock-in side reads PO receipts; the stock-out side
-reads transfer orders (which is why the 1.0 importer must populate
-`ItemFulfillmentItems.transferOrderItemId` — see the import doc).
+`_qtyOnOrder` was added alongside these. The stock-out side reads transfer orders (which is why the
+1.0 importer must populate `ItemFulfillmentItems.transferOrderItemId` — see the import doc).
+
+### Stock-in now reads inventory adjustments, NOT PO item receipts (changed 2026-08-31)
+
+Per the **2026-08-27 TOGa Supply meeting**: NetSuite has no "stocking" concept, so the only way stock
+is added is an **inventory adjustment** linked to the stocking order's item fulfillment (never
+directly to the PO). So `_Model_Nychh_Item::_qtyReceived` was changed to the **net
+`SUM(InventoryAdjustmentItems.quantityAdjustBy)`**, joined
+`InventoryAdjustmentItems.itemFulfillmentItemId → ItemFulfillmentItems.salesOrderItemId →
+SalesOrderItems` where `SalesOrderItems.itemId = Items.id`. This **supersedes** the old PO-item-receipt
+basis. Because on-hand and backordered both derive from `received`, they now use adjustments too.
+
+- **The adjustment↔fulfillment link** is the direct FK `InventoryAdjustmentItems.itemFulfillmentItemId`
+  (recent; NULL on older adjustments). Details on
+  [NYCHH inventory-adjustment → item-fulfillment linking](./netsuite-inventory-adjustment-fulfillment-link.md).
+- **Implicit stocking filter:** joining through `ItemFulfillmentItems.salesOrderItemId` counts only
+  **stocking-side** fulfillments — transfer-side fulfillment items have that column NULL — and all
+  Client_Nychh SalesOrders are stocking orders by the import routing.
+- **⚠ Reads 0.00 today, by design.** Verified in prod Client_Nychh 2026-08-31: `InventoryAdjustmentItems`
+  has 292 rows but **0** carry `itemFulfillmentItemId`, and all 351 `ItemFulfillmentItems` are
+  transfer-side (`salesOrderItemId = 0`). INNER JOINs make an unlinked adjustment contribute 0, so every
+  item reads 0 **until the NetSuite integration backfills the link** — expected, not a bug.
+
+## Per-PO-line quantities — `_Model_Nychh_PurchaseOrderItem` (new 2026-08-31)
+
+`_Model_Nychh_PurchaseOrderItem extends _Model_Client_PurchaseOrderItem` gives the **same quantities
+as Item level, but limited to a single purchase-order line** (previously these existed only at Item
+level), which NYCHH needs for PO-specific fulfillment.
+
+- **`_qtyReceived`** — adjustment stock-in (same as Item) but scoped to the PO line via
+  `PurchaseOrderItems_SalesOrderItems` (the PO→SO stocking bridge; see the bridge note below).
+- **`_qtyCommitted`** — Transfer-Order based, scoped to the PO line via
+  `PurchaseOrderItems_TransferOrderItems`, mirroring the Item-level two-branch model.
+- **`_qtyOnHand` / `_qtyAvailable` / `_qtyBackordered` / `_qtyOnOrder`** are **re-declared verbatim** on
+  the child so early-bound `self::` rebinds to the new leaf `_qtyReceived`/`_qtyCommitted` (established
+  framework pattern — a composite `FIELD_SQL` method that calls `self::` must be re-declared on the
+  child, not inherited). `_qtyBackordered` is floored at 0 with `GREATEST`, matching Item level.
+
+> **⚠ Signature must match the parent EXACTLY** when overriding a `FIELD_SQL` static method — an added
+> param type is a **fatal at class load** that `php -l` does NOT catch. Verified this session by
+> php-reviewer + sql-reviewer.
+
+### Which SO↔PO bridge scopes the PO line (they are two directional tables, not duplicates)
+
+The item-level bridges mirror the header-level SO↔PO direction split documented on
+[SO↔PO bridge direction](../../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md):
+
+- `PurchaseOrderItems_SalesOrderItems` — **SO items created FROM a PO item** (PO→SO stocking direction);
+  the **populated/canonical** one for stocking (682 rows in prod). PO-line stock-in scopes on this.
+- `SalesOrderItems_PurchaseOrderItems` — PO items created FROM a SO item (3 rows).
+
+Verified 0 SO lines map to >1 PO line, so PO-line `received` **cannot double-count**. Optional deferred
+hardening (not done): a `UNIQUE(purchaseOrderItemId, salesOrderItemId)` on the bridge as defense-in-depth.
+
+- **⚠ PO-level outbound reads 0 until a separate backfill.** `_qtyCommitted` depends on
+  `PurchaseOrderItems_TransferOrderItems`, which is currently **empty (0 rows)** in prod — so PO-level
+  outbound reads 0 until the transfer-order import populates that bridge. Separate import gap, not this change.
+
+### Index coverage / schema
+
+No `dbchanges2` file — pure calculated `FIELD_SQL` in PHP. All correlation columns
+(`InventoryAdjustmentItems.itemFulfillmentItemId`, `ItemFulfillmentItems.salesOrderItemId`,
+`SalesOrderItems.itemId`, both bridge FKs) are already indexed.
 
 ## V2 field enablement — how the TransferOrder POST was made to work
 
@@ -153,11 +220,28 @@ pattern (default a NOT NULL non-writable column in the model, never send it) is
   trait on the client-override model) AND the ACL/metadata rows exist.** Declaring without the ACL
   row, or granting the ACL without the declaration, each fails with its own error — see the peeled
   sequence above.
-- **These quantity overrides are NYCHH-only.** They live on `_Model_Nychh_Item`; do not lift them to
-  the base `_Model_Client_Item` — other clients do not have the stocking/transfer two-branch model.
+- **These quantity overrides are NYCHH-only.** They live on `_Model_Nychh_Item` and
+  `_Model_Nychh_PurchaseOrderItem`; do not lift them to the base `_Model_Client_*` — other clients do
+  not have the stocking/transfer two-branch model.
+- **A 0.00 quantity for NYCHH is expected today, not a bug.** Stock-in reads inventory-adjustment links
+  that are not backfilled yet, and PO-level outbound reads a still-empty
+  `PurchaseOrderItems_TransferOrderItems` bridge (see above).
 
 ## Change history
 
+- 2026-08-31 — **Stock-in flipped from PO item receipts → inventory adjustments** (per the 2026-08-27
+  TOGa Supply meeting: NetSuite has no stocking concept, stock is added only by an inventory adjustment
+  linked to the stocking order's item fulfillment). Changed `_Model_Nychh_Item::_qtyReceived` to net
+  `SUM(InventoryAdjustmentItems.quantityAdjustBy)` joined
+  `itemFulfillmentItemId → ItemFulfillmentItems.salesOrderItemId → SalesOrderItems` (`itemId = Items.id`);
+  on-hand and backordered follow. Added the **NYCHH-only `_Model_Nychh_PurchaseOrderItem`** for per-PO-line
+  quantities (same logic scoped to the PO line via `PurchaseOrderItems_SalesOrderItems` for received and
+  `PurchaseOrderItems_TransferOrderItems` for committed; composite `FIELD_SQL` methods re-declared verbatim
+  to rebind early-bound `self::`; backordered floored with `GREATEST`). Both read **0.00 in prod today** by
+  design — the adjustment↔fulfillment links are not backfilled (292 adjustment items, 0 linked; all 351
+  fulfillment items transfer-side) and `PurchaseOrderItems_TransferOrderItems` is empty. No dbchanges2
+  (pure `FIELD_SQL`; correlation columns already indexed); double-count ruled out (0 SO lines map to >1 PO
+  line). `php -l` clean; php-reviewer 0 critical, sql-reviewer warnings resolved. (jcardinal)
 - 2026-08-28 — Discovered that the transfer-order enablement on **prod and sandbox-client is
   UNTRACKED**: record ACL for 312/313 (roles 1 and 3), their logic-group/expression chain, field ACL
   for all 17 RecordFields, and the `TransferOrderItems.dtCreated`/`dtUpdated` columns all exist with

package/package.json

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