toga-ai 1.0.52 → 1.0.53

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

@@ -2,6 +2,6 @@
 
 | 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 |
+| [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: Item Fulfillments for Sales Order Items TableView (tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | The Compass TableView `item-fulfillments-for-sales-order-items` (`TableViews.id = 13` in Client_Compass) was rebuilt as part of the tracking-number bridge migra | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql |
 | [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,10 +5,12 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-06-08
+updated: 2026-06-11
 owners: [jcardinal]
 files:
   - _underscore/Model/Compass/AdvanceShippingNotice.php
+  - api2/Component/Api/Cxml/Cxml.php
+  - dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql
 related:
   - ../../../2.0/apps/_underscore/features/recursive-item-fulfillments.md
 ---
@@ -21,41 +23,81 @@ IFIUs for serialized units, and IF packages for tracking. ASNs arrive two ways:
 **cXML** (direct V2 API) and the worker email cron
 `3b_import_strategic_systems_advance_shipping_notices.php`.
 
+Tracking numbers are propagated across **every** ASN and IF granularity (see *Tracking number
+propagation* below), so a single ShipNotice tracking number lands at the header, item, and
+unit level on both sides — not just on one unit.
+
 ## Key files / entry points
+- `api2/Component/Api/Cxml/Cxml.php` — the cXML `ShipNoticeRequest` translator that builds
+  the `/advance-shipping-notices` POST payload.
 - `_underscore/Model/Compass/AdvanceShippingNotice.php` — `postPost(&$api, &$payload)`.
 - Fires only when the Compass ASN `ApiPayloadInterceptors` rows exist (interceptor is DB-driven).
+- `Model/Compass/Usa/` and `Model/Compass/Canada/` ASN classes are **empty subclasses** that
+  inherit `postPost` from `_Model_Compass_AdvanceShippingNotice` — edit the parent.
 
 ## How it works
 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 read its ASN units.
-5. Per ASN unit: if it has a Unit (serialized) → POST an IFIU; if it is tracking-only
-   (`unitId IS NULL`) → collect its tracking number for an IF package instead.
+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).
 
+## Tracking number propagation
+The cXML translator maps each `ShipControl` block's tracking number to a line via its
+`LineNumber` Extrinsic (it iterates **all** ShipControls and **all** ShipNoticeItems, not just
+`[0]`), then attaches the number at every level. End state for a cXML ShipNotice:
+
+| Table | Populated by |
+|---|---|
+| `AdvanceShippingNotices_TrackingNumbers` | cXML payload (ASN header) |
+| `AdvanceShippingNoticeItems_TrackingNumbers` | cXML payload (matched line's item) |
+| `AdvanceShippingNoticeItemUnits_TrackingNumbers` | cXML payload (tracking-only unit) |
+| `ItemFulfillments_TrackingNumbers` | `postPost` IF package |
+| `ItemFulfillmentItems_TrackingNumbers` | `postPost` (copies ASN-item tracking) |
+| `ItemFulfillmentItemUnits_TrackingNumbers` | `postPost` — **only when serialized units exist** |
+
+Fix-forward only (decided 2026-06-11): applies to new ShipNotices; existing records are not
+backfilled.
+
 ## Data model
 - `AdvanceShippingNoticeUnits.unitId` is nullable (tracking-only units have NULL).
 - `ItemFulfillmentItemUnits.unitId` is **NOT NULL** — a tracking-only unit can never be an
-  IFIU; its tracking belongs on an `ItemFulfillmentPackage`.
-- Compass tracking lives in `ItemFulfillmentPackages` (header-level); IFIUs are only for
-  genuinely serialized units.
+  IFIU; its tracking belongs on an `ItemFulfillmentPackage` / `ItemFulfillments_TrackingNumbers`.
+  So for a tracking-only ShipNotice (no serialized units, the Office Depot norm) the IFIU
+  bridge legitimately stays empty — there are no IF item units to attach to.
+- Tracking bridge Records (Core): ASN = 216 (unit) / 217 (item) / 218 (header);
+  IF = 317 (header) / 318 (item) / 319 (unit). All six are registered inherent children of
+  their parents, so the nested payload keys are accepted with no metadata migration.
 
 ## Client variations
 Compass USA handler (`Model/Compass/`), extending `_Model_Client_AdvanceShippingNotice`.
-Compass Canada (`Model/Compass/Canada/`) is a separate sub-client.
+Compass Canada (`Model/Compass/Canada/`) is a separate sub-client. The Compass cXML API
+(Core `ClientApiIdentities` identity `153531108`, clientId 2) holds roles 1 and 3.
 
 ## Gotchas / known issues
+- **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`,
+  so ASN-item-level tracking POSTs were rejected (`EZ-1`). `dbchanges2/Client_Compass/2026-06-11
+  - AsnItemTrackingNumberAcl.sql` grants role 3 CRUD + role 7 read at the record level and
+  roles 1/3/4 writable at the field level, mirroring sibling Record 216. **This SQL must be
+  executed against the Compass DB before the cXML change works end-to-end.**
 - **Tracking-only ASN units (the majority — ~56k of ~101k in prod):** before 2026-06-08 the
   IFIU query used `INNER JOIN Units`, silently dropping NULL-`unitId` rows, so cXML shipments
   produced an IF + IFI with **no IFIU and no package — tracking was lost**. Fixed: `LEFT
   OUTER JOIN Units` + route tracking-only units to IF packages. Historical records (e.g.
-  SO SA132502 / IF 66997) are **not backfilled** — fix-forward only; a one-time repair is
-  still an open decision.
+  SO SA132502 / IF 66997) are **not backfilled** — fix-forward only.
 - Interceptor is **DB-driven**: `postPost` does nothing without the Compass
   `ApiPayloadInterceptors` rows in that env.
 - The IF is named after the SO number; an already-existing IF with that number is reused.
+- **cXML SQL-injection hardening (2026-06-11):** the `ShipNoticeRequest` path interpolated the
+  cXML `Sender` Identity / SharedSecret and the OrderReference `orderID` (purchase order
+  number) straight into queries. These are now passed through `_Database::escape()`.
 - 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.
 

package/package.json

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