toga-ai 1.0.41 → 1.0.42

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

@@ -5,3 +5,4 @@
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.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 | _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 |

package/knowledge/2.0/apps/_underscore/features/tracking-number-bridges.md

@@ -0,0 +1,123 @@
+---
+title: Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-06-10
+owners: ["jcardinal"]
+files:
+  - _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
+related:
+  - recursive-item-fulfillments.md
+---
+
+## Summary
+
+Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`,
+`returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables across the ASN,
+Item Fulfillment (IF), and Item Receipt (IR) hierarchies. This migration moves all tracking
+into dedicated **`*_TrackingNumbers` bridge tables** (one consistent pattern per hierarchy
+level), so a record can carry multiple tracking numbers and the model is uniform. It also:
+
+- renames the ASN **`AdvanceShippingNoticeUnits`** table → **`AdvanceShippingNoticeItemUnits`**
+  (and its bridge + FK column `advanceShippingNoticeUnitId` → `advanceShippingNoticeItemUnitId`),
+- consolidates **`ItemFulfillmentPackages`** (header-level tracking) into
+  **`ItemFulfillments_TrackingNumbers`** and **drops the packages table**,
+- makes tracking a model concept submitted/read **as an inherent child of the parent record**
+  (not a scalar field).
+
+## The bridge pattern
+
+Each hierarchy level gets a bridge keyed to its parent plus `trackingNumberId`
+(+ `returnTrackingNumberId` on ASN and IF bridges; IR has no returns):
+
+| Level | Bridge table | Core Record id | Route (inherent-child key) |
+|---|---|---|---|
+| ASN | AdvanceShippingNotices_TrackingNumbers | 218 | advance-shipping-notice-tracking-numbers |
+| ASN item | AdvanceShippingNoticeItems_TrackingNumbers | 217 | advance-shipping-notice-item-tracking-numbers |
+| ASN unit | AdvanceShippingNoticeItemUnits_TrackingNumbers | 216 (renamed) | advance-shipping-notice-item-unit-tracking-numbers |
+| IF | ItemFulfillments_TrackingNumbers | 317 (new) | item-fulfillment-tracking-numbers |
+| IF item | ItemFulfillmentItems_TrackingNumbers | 318 (new) | item-fulfillment-item-tracking-numbers |
+| IF item unit | ItemFulfillmentItemUnits_TrackingNumbers | 319 (new) | item-fulfillment-item-unit-tracking-numbers |
+| IR | ItemReceipts_TrackingNumbers | 320 (new) | item-receipt-tracking-numbers |
+| IR item | ItemReceiptItems_TrackingNumbers | 321 (new) | item-receipt-item-tracking-numbers |
+| IR item unit | ItemReceiptItemUnits_TrackingNumbers | 322 (new) | item-receipt-item-unit-tracking-numbers |
+
+All bridges are registered as **`InherentRecordChildren`** of their parent record, so the
+engine derives the payload key from the bridge route (kebab→camel) — e.g. an ASN unit's
+tracking is submitted as `advanceShippingNoticeItemUnitTrackingNumbers: [{ trackingNumber: {...},
+returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTrackingNumbers`.
+
+## Key files / entry points
+
+- **Bridge models** — `Model/Client/<Parent>/TrackingNumber.php` (e.g. `ItemFulfillmentItemUnits/TrackingNumber.php`).
+  The renamed ASN unit model is `Model/Client/AdvanceShippingNoticeItemUnit.php`; the old
+  `AdvanceShippingNoticeUnit.php` + `AdvanceShippingNoticeUnits/TrackingNumber.php` were deleted.
+- **Recursive feature** — `Model/Client/ItemFulfillment.php`: `reconcileUpstreamUnits` and
+  `reconcileUpstreamPackages` now read/write the bridges (POST `/item-fulfillment-item-unit-tracking-numbers`
+  and `/item-fulfillment-tracking-numbers`); unit deletes cascade to the inherent-child bridge rows.
+  The FedEx/shipping-label methods read header tracking from `ItemFulfillments_TrackingNumbers`.
+- **Prudential interceptor** — `Model/Prudential/AdvanceShippingNotice.php::prePost` (see the
+  Prudential client doc).
+- **cXML inbound** — `api2/Component/Api/Cxml/Cxml.php` emits the new key + bridge-child tracking.
+- **DB** — `dbchanges2/Core/...` (records/fields/ACL/inherent-children, record-41 teardown),
+  `dbchanges2/Client/...` (renames, bridges, migrations, ACL) split into an additions file and a
+  companion `..._DROPS.sql` for the column/table drops to run after confirmation.
+
+## Data model
+
+- New bridges: `id, uuid, <parentFk>, trackingNumberId (NULL), [returnTrackingNumberId (NULL)]`,
+  `InnoDB / utf8mb4_unicode_ci`, `UNIQUE(uuid)`, `UNIQUE(<parentFk>, trackingNumberId)`, FKs to
+  the parent + `TrackingNumbers`.
+- Dropped (in the DROPS file): `AdvanceShippingNoticeItemUnits.trackingNumberId/returnTrackingNumberId`,
+  `ItemFulfillmentItemUnits.trackingNumberId`, `ItemReceiptItems.trackingNumberId`,
+  `ItemReceiptItemUnits.trackingNumberId`, and the entire `ItemFulfillmentPackages` table.
+- Core: Records 61 (unit) + 216 (unit bridge) renamed; new Records 317–322 + RecordFields 2171–2200;
+  `returnTrackingNumberId` RecordFields added to 216/217/218; dropped RecordFields 334/652/1431/1576/1577;
+  record 41 (item-fulfillment-packages) fully removed. Label settings (`DefaultRecordFieldSettings`)
+  and `Records.labelRecordFieldId` are **repointed** from dropped fields to the new bridge fields.
+
+## Client variations
+
+- **Compass (Client_Compass / compass-usa):** ASN→IF auto-creation (`Model/Compass/AdvanceShippingNotice.php`)
+  posts unit tracking + header tracking via the bridge routes; `Model/Compass/SalesOrder.php::_trackingNumbers`
+  reads through the bridges. The `item-fulfillments-for-sales-order-items` TableView was rebuilt
+  (see the compass-usa client doc).
+- **Prudential (Client_Prudential):** Dell posts the legacy `advanceShippingNoticeUnits` key with flat
+  tracking — a PRE/POST interceptor rewrites it (see the prudential client doc).
+- **NetSuite-integrated clients:** `Trait/Netsuite/ItemFulfillment.php` now reads
+  `itemFulfillmentTrackingNumbers` and posts `/item-fulfillment-tracking-numbers`. The 1.0 library
+  `App_Api_Toga2` (`library/app/api/toga2.php`) got the same change for the worker tier.
+
+## Gotchas / known issues
+
+- **Tracking is now an inherent child, not a scalar.** Any producer that sent a flat `trackingNumber`
+  on a unit must nest it under the unit's `*TrackingNumbers` child array, or it is silently dropped.
+- **Migration FK pitfalls (all handled in the SQL):** deleting `RecordFields` hits `DefaultRecordFieldSettings`
+  FKs (repoint first); deleting `AclRecordPermissions` hits the `AclLogicGroups`→`AclLogicGroupExpressions`
+  chain (record-41 teardown wraps it in `SET FOREIGN_KEY_CHECKS=0`); deleting `TableViewFields` hits
+  `TableViews.sortPrimaryTableViewFieldId` (null it first, re-point after); self-referencing `INSERT … NOT EXISTS`
+  on the target table errors 1093 (use a derived table); and orphaned/dangling `trackingNumberId` values
+  fail the bridge FK 1452 (join `TrackingNumbers` so orphans become NULL / are skipped).
+- **UUIDs in SQL:** generated with `RANDOM_BYTES()` (MySQL 8) — never MySQL `UUID()` (per 2.0 standard).
+- **Dropped FK constraint names vary per client** — drop them dynamically via `INFORMATION_SCHEMA` + PREPARE.
+- **Deploy coupling:** renames are NOT backward compatible — apply the DB migration and deploy
+  `_underscore` + `api2` + `worker` + `library` together. Run the additions/migrations DB file first;
+  run the companion `..._DROPS.sql` (and the Core deletes) only after the bridges + app are confirmed.
+
+## Related docs
+- Recursive Item Fulfillment feature (the upstream-sync engine this migration reworked).
+- compass-usa: ASN→Item Fulfillment, and the Item Fulfillment tracking TableView.
+- prudential: Dell ASN units interceptor.

package/knowledge/INDEX.md

@@ -9,7 +9,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 3 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 4 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 5 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 1 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)
@@ -21,4 +21,5 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **compass-usa** → [clients/compass-usa/INDEX.md](clients/compass-usa/INDEX.md)
 - **elite** → [clients/elite/INDEX.md](clients/elite/INDEX.md)
 - **nycdoe** → [clients/nycdoe/INDEX.md](clients/nycdoe/INDEX.md)
+- **prudential** → [clients/prudential/INDEX.md](clients/prudential/INDEX.md)
 

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

@@ -3,4 +3,5 @@
 | 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: 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/item-fulfillment-tracking-tableview.md

@@ -0,0 +1,46 @@
+---
+title: "Compass: Item Fulfillments for Sales Order Items TableView (tracking via bridge)"
+framework: "2.0"
+project: _Underscore
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-06-10
+owners: ["jcardinal"]
+files:
+  - dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql
+related:
+  - ../../../2.0/apps/_underscore/features/tracking-number-bridges.md
+---
+
+## Summary
+
+The Compass TableView `item-fulfillments-for-sales-order-items` (`TableViews.id = 13` in
+Client_Compass) was rebuilt as part of the tracking-number bridge migration. It was rooted at
+**Units** with INNER joins (so non-serialized items with no unit never appeared) and sourced the
+outbound tracking number from the now-dropped `ItemFulfillmentItemUnits.trackingNumberId`.
+
+## How it works (new definition)
+
+- **Base record re-rooted** to `ItemFulfillmentItems` (record 29).
+- Joins: INNER `SalesOrderItems`; **OUTER** `ItemFulfillmentItemUnits` (so items without a
+  serialized unit still return); OUTER `Units`; OUTER the new `ItemFulfillmentItemUnits_TrackingNumbers`
+  bridge (record 319) → OUTER `TrackingNumbers` → OUTER `ShippingCarriers`.
+- Columns, in order: **Sales Order Line Number, Quantity Fulfilled (new — `ItemFulfillmentItems.quantity`),
+  Outbound Tracking #, Carrier, Serial #, Asset Tag.**
+- Default sort (`TableViews.sortPrimaryTableViewFieldId`) re-pointed to the line-number field.
+
+## Gotchas / known issues
+
+- Tracking is sourced through the bridge join (`ItemFulfillmentItemUnits_TrackingNumbers.trackingNumberId`),
+  NOT the dropped column. The bridge record/fields (319 / 2183 itemFulfillmentItemUnitId / 2184
+  trackingNumberId) come from the Core migration and must exist before this file runs.
+- `TableViews.sortPrimaryTableViewFieldId` is a FK to `TableViewFields`; it must be set NULL before the
+  old fields are deleted, then re-pointed (via a multi-table UPDATE, not a self-subquery, to avoid 1093).
+- `TableViewFields` must be deleted before `TableViewJoins` (`tableViewJoinId` FK).
+
+## Client variations
+This is Compass-only. The underlying bridge model is shared (see the _underscore feature doc).
+
+## Related docs
+- 2.0 _underscore: Tracking-Number Bridge Migration.

package/knowledge/clients/prudential/INDEX.md

@@ -0,0 +1,6 @@
+# Client: prudential
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Prudential: Dell ASN units PRE/POST interceptor (legacy key + flat tracking)](features/dell-asn-units-interceptor.md) | 2.0 | After the tracking-number bridge migration, the ASN unit route was renamed (`advance-shipping-notice-units` → `advance-shipping-notice-item-units`), so the inhe | _underscore/Model/Prudential/AdvanceShippingNotice.php, dbchanges2/Client_Prudential/2026-06-10 - AsnUnitsInterceptor.sql |
+| [Prudential](profile.md) | 2.0 | Prudential is a TOGA client whose device-fulfillment flow is driven by **Dell** via the Dell API (`Client_Prudential.Apis.id = 2`). |  |

package/knowledge/clients/prudential/features/dell-asn-units-interceptor.md

@@ -0,0 +1,51 @@
+---
+title: "Prudential: Dell ASN units PRE/POST interceptor (legacy key + flat tracking)"
+framework: "2.0"
+project: _Underscore
+client: prudential
+type: client-feature
+status: active
+updated: 2026-06-10
+owners: ["jcardinal"]
+files:
+  - _underscore/Model/Prudential/AdvanceShippingNotice.php
+  - dbchanges2/Client_Prudential/2026-06-10 - AsnUnitsInterceptor.sql
+related:
+  - ../../../2.0/apps/_underscore/features/tracking-number-bridges.md
+---
+
+## Summary
+
+After the tracking-number bridge migration, the ASN unit route was renamed
+(`advance-shipping-notice-units` → `advance-shipping-notice-item-units`), so the inherent-child
+key became `advanceShippingNoticeItemUnits`, and unit tracking now lives in the bridge child
+`advanceShippingNoticeItemUnitTrackingNumbers` (the scalar `trackingNumber`/`returnTrackingNumber`
+fields on the unit were dropped). **Dell will not change their payload**, so a Prudential-only
+interceptor translates it on the way in.
+
+## How it works
+
+- **`Model/Prudential/AdvanceShippingNotice.php::prePost(&$api, &$payload)`** — for each
+  `$payload->advanceShippingNoticeItems[]`: renames the legacy `advanceShippingNoticeUnits` key to
+  `advanceShippingNoticeItemUnits`, and lifts each unit's flat `trackingNumber` / `returnTrackingNumber`
+  into a single `advanceShippingNoticeItemUnitTrackingNumbers` bridge-child row, removing the flat fields.
+- **Registration** — `Client_Prudential.ApiPayloadInterceptors` row: `recordId = 55`
+  (advance-shipping-notices), `prePostProcessing = 'PRE'`, `httpMethod = 'POST'`, `apiId = 2` (Dell),
+  `isActive = 1`. The engine resolves `_Model_Client_AdvanceShippingNotice` → `_Model_Prudential_AdvanceShippingNotice`
+  by client identifier; **both** the DB interceptor row AND the model method are required for it to fire.
+
+## Inbound payload (Dell, unchanged)
+```
+advanceShippingNoticeItems: [ { quantity, advanceShippingNoticeUnits: [
+    { trackingNumber:{number}, returnTrackingNumber:{number}, unit:{serialNumber} } ] } ]
+```
+The interceptor rewrites each item to `advanceShippingNoticeItemUnits` with the tracking moved into
+`advanceShippingNoticeItemUnitTrackingNumbers`.
+
+## Gotchas
+- Scoped to `apiId = 2` so other (internal) Prudential callers — which already send the new shape —
+  are not double-transformed.
+- DB change lives in `dbchanges2/Client_Prudential/`.
+
+## Related docs
+- 2.0 _underscore: Tracking-Number Bridge Migration.

package/knowledge/clients/prudential/profile.md

@@ -0,0 +1,34 @@
+---
+title: Prudential
+framework: "2.0"
+project: _Underscore
+client: prudential
+type: profile
+status: active
+updated: 2026-06-10
+owners: ["jcardinal"]
+files: []
+related:
+  - features/dell-asn-units-interceptor.md
+---
+
+## Summary
+Prudential is a TOGA client whose device-fulfillment flow is driven by **Dell** via the Dell
+API (`Client_Prudential.Apis.id = 2`). Dell posts Advance Shipping Notices (with tracking and
+return-tracking per unit) into the 2.0 platform (DB `Client_Prudential`); the 1.0 worker tier
+(`crons/toga2/prudential/`) handles NetSuite sync, ServiceNow (RITM) close/ship updates, and
+order-status transmissions.
+
+## Integrations
+- **Inbound:** Dell API → POST `/v2/advance-shipping-notices` (creates ASNs + units + tracking).
+- **Outbound (worker crons):** `transmissions_to_netsuite.php`, `transmit_ordershipped_updates_prudential.php`,
+  `transmit_closecomplete_updates_prudential.php`, `transmit_order_delivered_updates_from_fedex_toga2.php`,
+  `update_tracking_number_from_netsuite_to_toga.php`, `manually_insert_ASN.php`.
+
+## Gotchas
+- Dell will not change their payload shape — see the Dell ASN units interceptor feature doc for the
+  PRE/POST translation that keeps their feed working after the tracking-number bridge migration.
+
+## Related docs
+- Dell ASN units interceptor.
+- 2.0 _underscore: Tracking-Number Bridge Migration.

package/package.json

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