toga-ai 1.0.73 → 1.0.74

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

@@ -2,7 +2,7 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
-| [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF) on the upstream SalesOrder. | _underscore/Model/Compass/AdvanceShippingNotice.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql |
+| [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF) on the upstream SalesOrder. | _underscore/Model/Compass/AdvanceShippingNotice.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql, dbchanges2/Client_Compass/2026-06-15b - BackfillSA132781ItemFulfillmentTracking.sql |
 | [Compass: Item-Fulfillment TableViews (for-sales-order-items & for-sales-orders, tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | Two sibling Compass TableViews in `Client_Compass` display fulfilled items in toga2-supply, both driven by `TableViews` / `TableViewJoins` / `TableViewFields` c | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql, dbchanges2/Client_Compass/2026-06-11 - ItemFulfillmentsForSalesOrdersTableView.sql, dbchanges2/Client_Compass/2026-06-15a - FixItemFulfillmentTrackingNumberJoins.sql |
 | [Compass MITS PO → SO Item Linking](features/mits-po-to-so-item-linking.md) | 2.0 | MITS sends Compass inbound Purchase Orders (`POST /v2/purchase-orders`) against a Sales Order (`mitsSalesOrder`). | _underscore/Model/Compass/PurchaseOrder.php |
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |

package/knowledge/clients/compass-usa/features/asn-to-item-fulfillment.md

@@ -5,12 +5,13 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-06-11
+updated: 2026-06-15
 owners: [jcardinal]
 files:
   - _underscore/Model/Compass/AdvanceShippingNotice.php
   - api2/Component/Api/Cxml/Cxml.php
   - dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql
+  - dbchanges2/Client_Compass/2026-06-15b - BackfillSA132781ItemFulfillmentTracking.sql
 related:
   - ../../../2.0/apps/_underscore/features/recursive-item-fulfillments.md
 ---
@@ -36,16 +37,28 @@ unit level on both sides — not just on one unit.
   inherit `postPost` from `_Model_Compass_AdvanceShippingNotice` — edit the parent.
 
 ## How it works
+As of **2026-06-15** the handler **reconciles tracking onto whatever fulfillment exists** —
+it no longer only attaches tracking when it creates new fulfillment (see *Change history* and
+the gotcha about already-fulfilled orders). Flow:
+
 1. Read ASN → resolve PO → SO via `SalesOrders_PurchaseOrders`; skip if no SO.
-2. Select ASN items whose SOI still has unfulfilled qty (`SOI.quantity > SUM(IFI.quantity)`).
-3. Reuse the IF if one already exists with the SO number, else POST a new IF.
-4. Per ASN item: POST an IFI (qty = ASN item qty); then copy that ASN item's tracking numbers
-   (`AdvanceShippingNoticeItems_TrackingNumbers`) onto the IF item via
-   `POST /item-fulfillment-item-tracking-numbers` → `ItemFulfillmentItems_TrackingNumbers`.
-5. Per ASN unit: if it has a Unit (serialized) → POST an IFIU (carrying unit tracking); if it
-   is tracking-only (`unitId IS NULL`) → collect its tracking number for an IF package instead.
-6. Create one IF package per unique tracking number (header-level tracking merged with
-   tracking-only ASN-unit tracking, deduped by tracking-number uuid).
+2. Select **all** ASN items mapped to a SalesOrderItem (NO "unfulfilled only" filter), carrying
+   each SOI's `quantity` and already-`SUM`med fulfilled qty.
+3. Per ASN item, compute `remaining = SOI.quantity − fulfilled` (rounded to kill float dust):
+   - **`remaining > 0`** (create path, unchanged): reuse the SO-numbered IF or POST a new one,
+     POST an IFI; that new IFI is the tracking target. Additional SO-numbered IFs are acceptable.
+   - **`remaining <= 0`** (reconcile path, new): the tracking targets are the **existing IFIs**
+     for that SOI (resolved via `ItemFulfillmentItems.salesOrderItemId` → their `itemFulfillmentId`),
+     **not** an SO-number lookup — NetSuite/toga2-supply IFs are `F`-numbered, not SO-numbered.
+4. Copy the ASN item's tracking (`AdvanceShippingNoticeItems_TrackingNumbers`) onto each target
+   IFI via `POST /item-fulfillment-item-tracking-numbers` → `ItemFulfillmentItems_TrackingNumbers`
+   — **idempotent** (skipped if the bridge row already exists; ASNs get re-POSTed).
+5. Per ASN unit: serialized (has a Unit) → attach unit tracking to the matching IFIU
+   (`POST /item-fulfillment-item-unit-tracking-numbers`; create the IFIU only on the create path);
+   tracking-only (`unitId IS NULL`) → collect its tracking for an IF package.
+6. Create one IF package per unique tracking number (header-level merged with tracking-only
+   ASN-unit tracking, deduped by tracking-number **id**) on **each involved IF** — i.e. only the
+   IF(s) that received this ASN's tracking — all idempotent.
 
 ## Tracking number propagation
 The cXML translator maps each `ShipControl` block's tracking number to a line via its
@@ -62,7 +75,10 @@ The cXML translator maps each `ShipControl` block's tracking number to a line vi
 | `ItemFulfillmentItemUnits_TrackingNumbers` | `postPost` — **only when serialized units exist** |
 
 Fix-forward only (decided 2026-06-11): applies to new ShipNotices; existing records are not
-backfilled.
+backfilled (one-off backfills repair specific orders — e.g. `2026-06-15b` for SA132781).
+
+As of 2026-06-15 propagation also fires when the IF **already exists** (reconcile path), so the
+table above is populated even for SOs fulfilled out-of-band before the ASN arrived.
 
 ## Data model
 - `AdvanceShippingNoticeUnits.unitId` is nullable (tracking-only units have NULL).
@@ -80,6 +96,24 @@ Compass Canada (`Model/Compass/Canada/`) is a separate sub-client. The Compass c
 (Core `ClientApiIdentities` identity `153531108`, clientId 2) holds roles 1 and 3.
 
 ## Gotchas / known issues
+- **ASN arriving AFTER the SO is already fulfilled (fixed 2026-06-15):** when an SO is fulfilled
+  out-of-band (NetSuite/toga2-supply creates `F`-numbered IFs) **before** its ASN arrives,
+  `postPost` previously found zero unfulfilled ASN items and skipped the **entire** propagation
+  block (the old `if ($asnItemsQuery->getRowCount())` gate wrapped even the header-package
+  creation) — so the ASN's tracking was lost at every level. Symptom: SO **SA132781** (id 105943)
+  had tracking on the ASN (header/item/unit) but none on its IFs (68063/68154). Fix: reconcile
+  onto existing fulfillment (see *How it works*). Forward-only; SA132781 repaired by the backfill
+  migration `2026-06-15b`.
+- **A NULL `AdvanceShippingNoticeItemUnits.unitId` is CORRECT — do NOT add a NOT NULL
+  constraint.** Office Depot (vendorId 1) ships via cXML and **never sends serial numbers**;
+  the cXML→JSON translator deliberately creates a tracking-only ASN unit (no `unit`, NULL
+  `unitId`) purely to carry the unit-level tracking number. Verified against the raw cXML
+  (`Logs_Compass.Api`) for SA132781. A NOT NULL constraint would reject the majority of Compass
+  ASN volume (~56k of ~101k units are tracking-only) and break tracking ingestion. A serialized
+  `Unit` seen on the IF side (e.g. created by NetSuite) is unrelated to the tracking-only ASN unit.
+- **Idempotency:** every tracking attach is guarded by a SELECT-before-POST on the bridge table,
+  so re-POSTing the same ASN does not duplicate `ItemFulfillment(s|Items|ItemUnits)_TrackingNumbers`
+  rows. New attach helpers depend on this — keep the guard if extending.
 - **Record 217 ACL gap (fixed 2026-06-11):** `AdvanceShippingNoticeItems_TrackingNumbers`
   (Record 217) had **zero** `AclRecordPermissions` and its `advanceShippingNoticeItemId`
   (RecordField 1440) / `trackingNumberId` (1441) fields had **zero** `AclFieldPermissions`,
@@ -101,5 +135,16 @@ Compass Canada (`Model/Compass/Canada/`) is a separate sub-client. The Compass c
 - Separate latent bug in the 1.0 worker: the Strategic Systems cron's no-serials branch
   builds `$itemLevelTrackingNumbers` but never attaches it to the ASN payload.
 
+## Change history
+Dated one-liners, newest first.
+- 2026-06-15 — `postPost` rewritten to reconcile ASN tracking onto **existing** fulfillment
+  (not just newly-created IFs), idempotently; fixes lost tracking when the SO was fulfilled
+  out-of-band before the ASN (e.g. SA132781). Confirmed NULL `unitId` is by-design for Office
+  Depot tracking-only units (no NOT NULL constraint). Backfill `2026-06-15b` repairs SA132781. (jcardinal)
+- 2026-06-11 — Record 217 ACL grant so ASN-item-level tracking POSTs succeed; cXML SQL-injection
+  hardening; tracking propagated across all ASN/IF granularities. (jcardinal)
+- 2026-06-08 — IFIU query switched to `LEFT OUTER JOIN Units`; tracking-only units routed to IF
+  packages (previously dropped by an INNER JOIN). (jcardinal)
+
 ## Related docs
 - Recursive Item Fulfillments (upstream mirroring) — the engine these IFs/packages feed.

package/package.json

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