toga-ai 1.0.104 → 1.0.105

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

@@ -3,7 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [_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 |
+| [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/Model/Client/ItemFulfillments/TrackingNumber.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 |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.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 |

package/knowledge/2.0/apps/_underscore/features/carrier-shipping-labels.md

@@ -6,10 +6,11 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-10
+updated: 2026-06-16
 owners: [mhammontree]
 files:
   - _underscore/Model/Client/ItemFulfillment.php
+  - _underscore/Model/Client/ItemFulfillments/TrackingNumber.php
   - _underscore/Component/Library/Carriers/Ups/Ups.php
   - _underscore/Trait/Netsuite/ItemFulfillment.php
   - _underscore/Trait/Netsuite/SalesOrder.php
@@ -39,7 +40,10 @@ decision** (dev lead Jeff, June 2026) that supersedes what the code currently do
   the DB storage field, return `{ trackingNumber, pdfLabel, fileInternalId }` or
   `{ error, trackingNumber }`. UPS path now checks `$shipmentResponse->success` and
   fast-fails on an empty service code (it previously swallowed UPS errors and surfaced
-  a misleading "Failed to save PDF to NetSuite").
+  a misleading "Failed to save PDF to NetSuite"). These methods (plus `fulfill` and
+  `createNetsuiteItemFulfillment`'s package-detail query) resolve the tracking record by
+  joining **`ItemFulfillments_TrackingNumbers`** (the bridge); they previously joined the
+  dropped `ItemFulfillmentPackages` table — see Gotchas.
 - `_Component_Library_Carriers_Ups::submitShipmentRequest`
   (`Component/Library/Carriers/Ups/Ups.php`): returns `{ success, errorMessage,
   trackingNumber, encodedLabel }`.
@@ -104,8 +108,20 @@ attempted.
   recommended: always scope `getInventoryNumberFromSerialNumber` by location.
 - `createNetsuiteItemFulfillment` doesn't set carrier/method on the NS IF — it defaults
   (can show FedEx for a UPS shipment). Open item.
+- **Carrier-label queries joined the *dropped* `ItemFulfillmentPackages` table** (a
+  tracking-number-bridge migration write-back gap). `upsShipmentApi`, `fedexShipmentApi`,
+  `fulfill`, and `createNetsuiteItemFulfillment`'s package-detail query resolved the tracking
+  number by joining `ItemFulfillmentPackages` — retired by the bridge migration. Post-migration
+  that matched the **wrong/null** `TrackingNumbers` record, so the label + `number` saved to the
+  wrong row (the bridge-linked record's `labelPdfFile`/`number` stayed null → **reprint had no
+  label**) and the NS IF was built **without its tracking number**. **Fixed 2026-06-16** by
+  repointing all four joins to `ItemFulfillments_TrackingNumbers`. Diagnostic tell: the
+  bridge-linked `TrackingNumbers` row shows `number = NULL` after a "successful" ship. Backend
+  change — only effective once deployed to beta. Worth grepping `ItemFulfillmentPackage::TABLE`
+  across `_underscore`/`api2`/`library` for the same staleness elsewhere.
 
 ## Change history
+- 2026-06-16 — Repointed the carrier-label/NS-IF tracking-number queries (`upsShipmentApi`, `fedexShipmentApi`, `fulfill`, `createNetsuiteItemFulfillment`) from the dropped `ItemFulfillmentPackages` table to the `ItemFulfillments_TrackingNumbers` bridge — they had been saving the label/`number` to the wrong/null record (reprint `labelPdfFile` null; NS IF missing tracking). Confirmed working on beta. (mhammontree)
 - 2026-06-10 — Documented carrier shipping label mechanics (UPS/FedEx) + the authoritative GIF label-storage decision and NetSuite IF attachment. (mhammontree)
 
 ## Related docs

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

@@ -135,6 +135,7 @@ returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTracki
   **not** join `Records`. This gap belongs back in the migration (Core §7 + Client §6b + blank-client template).
 
 ## Change history
+- 2026-06-16 — Caught a migration code-update miss: four queries in `Model/Client/ItemFulfillment.php` (`upsShipmentApi`, `fedexShipmentApi`, `fulfill`, `createNetsuiteItemFulfillment`) still joined the dropped `ItemFulfillmentPackages` table to resolve tracking — repointed to `ItemFulfillments_TrackingNumbers`. See the carrier-shipping-labels doc. (mhammontree)
 - 2026-06-16 — Found + documented the bridge ACL gap: the migration creates bridge `AclRecordPermissions` (317–322) but not their `AclLogicGroups`/`AclLogicGroupExpressions`/`AclRecordExpressions` chain → 403 "No ACL Logic Groups defined" for non-Super-User reads (confirmed prod + all clients). Recorded the `slug='all'`/`sqlExpression='1'` fix for Core + per-client, plus the Client-DB `Records`-table caveat. (mhammontree)
 - 2026-06-10 — Documented the tracking-number bridge migration: scalar FK columns → `*_TrackingNumbers` bridge tables across ASN/IF/IR, ASN unit table rename, packages-table consolidation. (jcardinal)
 

package/package.json

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