toga-ai 1.0.156 → 1.0.157

package/knowledge/2.0/apps/_underscore/INDEX.md

@@ -8,3 +8,4 @@
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql |
 | [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | api2/Component/Api/V2/V2.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19b - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql |
+| [Units for Items for Purchase Orders — Data Structure](features/units-for-items-for-purchase-orders.md) | Describes how unit (serialized inventory) data is linked to sales-order and purchase-order line items behind the `units-for-items-for-purchase-orders` TableView |  |

package/knowledge/2.0/apps/_underscore/features/units-for-items-for-purchase-orders.md

@@ -0,0 +1,92 @@
+---
+title: Units for Items for Purchase Orders — Data Structure
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-06-22
+owners: ["bala"]
+files: []
+related: []
+---
+
+## Summary
+Describes how unit (serialized inventory) data is linked to sales-order and purchase-order
+line items behind the `units-for-items-for-purchase-orders` TableView. A unit only becomes
+visible in this view if it can be walked from the sales-order item out to a unit record. There
+are **two independent linkage paths** in the schema, and the view traverses only one of them —
+which is the root cause of "units not showing" cases.
+
+## How it works
+A `Unit` can be tied to an order line through either of two chains:
+
+**1. Receipt path (what this view follows):**
+```
+SalesOrderItems
+  -> SalesOrderItems_PurchaseOrderItems   (item-level bridge: salesOrderItemId, purchaseOrderItemId)
+  -> PurchaseOrderItems                   (PurchaseOrderItems.id = bridge.purchaseOrderItemId)
+  -> ItemReceiptItems                     (ItemReceiptItems.purchaseOrderItemId = PurchaseOrderItems.id)
+  -> ItemReceiptItemUnits                 (ItemReceiptItemUnits.itemReceiptItemId = ItemReceiptItems.id)
+  -> Units                                (ItemReceiptItemUnits.unitId)
+```
+
+**2. Fulfillment path (direct; NOT followed by this view):**
+```
+SalesOrderItems
+  -> ItemFulfillmentItems                 (ItemFulfillmentItems.salesOrderItemId = SalesOrderItems.id)
+  -> ItemFulfillmentItemUnits             (ItemFulfillmentItemUnits.itemFulfillmentItemId = ItemFulfillmentItems.id)
+  -> Units                                (ItemFulfillmentItemUnits.unitId)
+```
+
+The receipt path requires both the item-level bridge **and** an item receipt against the
+bridged purchase-order line. The fulfillment path reaches `SalesOrderItems` directly by
+`salesOrderItemId` with no purchase order or bridge involved.
+
+## Data model
+Header-level vs item-level bridges, and the level each transaction is anchored at:
+
+- **`PurchaseOrders_SalesOrders`** — *header* bridge: links a customer PO to a sales order
+  (`purchaseOrderId`, `salesOrderId`).
+- **`SalesOrderItems_PurchaseOrderItems`** — *item* bridge: links a sales-order line to a
+  vendor purchase-order line (`salesOrderItemId`, `purchaseOrderItemId`). This is the bridge
+  the receipt path depends on.
+- **Item receipts are PO-anchored only**: `ItemReceipts.purchaseOrderId`,
+  `ItemReceiptItems.purchaseOrderItemId` — there is **no sales-order FK on a receipt**. The
+  only way a received unit reaches a sales order is through the item bridge.
+- **Item fulfillments are SO-anchored**: `ItemFulfillments.salesOrderId`,
+  `ItemFulfillmentItems.salesOrderItemId`.
+- Both customer POs and vendor POs live in the same `PurchaseOrders` table, distinguished by
+  which bridge references them (header bridge = customer PO; item bridge via
+  `PurchaseOrderItems` = vendor PO).
+- `Items.inventoryType` governs whether units exist at all (see Gotchas).
+
+## Client variations
+None — uniform. The linkage structure is framework-level and identical across clients.
+
+## Gotchas / known issues
+- **The view only walks the receipt path.** A line whose units exist solely via the
+  fulfillment path (shipped from stock, never received against the bridged PO line) shows
+  **0 units** even though units physically exist. No data backfill can surface these — only a
+  resolver/view change that also walks the fulfillment path will.
+- **Missing item bridge → no units**, even when units were received. Without a
+  `SalesOrderItems_PurchaseOrderItems` row, the receipt path has no starting link.
+- **A present bridge is not sufficient.** If the bridged PO line has no
+  `ItemReceiptItemUnits`, the receipt path still resolves to nothing.
+- **`inventoryType` determines unit existence**: `SERIALIZED` and `HYBRID` items can produce
+  unit records; `NON_SERIALIZED` (bulk/consumable) never do. `HYBRID` items fulfilled as a
+  plain quantity (no serial capture) also produce no units — legitimately blank.
+- **Receipt-path counts are PO-line-wide.** Units surfaced reflect everything received against
+  the bridged PO line, which may exceed or differ from what was actually fulfilled to a given
+  sales order (over/under-attribution), because attribution is by PO line, not by the
+  fulfillment that shipped the unit.
+
+## Change history
+- 2026-06-22 — Documented the two-path units linkage model behind the
+  units-for-items-for-purchase-orders view and why the receipt-only traversal hides
+  fulfillment-only units. (bala)
+
+## Related docs
+- [[recursive-item-fulfillments]]
+- [[tracking-number-bridges]]

package/knowledge/INDEX.md

@@ -14,7 +14,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 9 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 10 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 8 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 4 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/package.json

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