toga-ai 1.0.103 → 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 | _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 |
+| [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

@@ -6,9 +6,10 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-10
-owners: ["jcardinal"]
+updated: 2026-06-16
+owners: ["jcardinal", "mhammontree"]
 files:
+  - api2/Component/Api/V2/V2.php
   - _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php
   - _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php
   - _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php
@@ -116,8 +117,26 @@ returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTracki
 - **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.
+- **⚠ Bridge ACL is incomplete — non-Super-User reads get 403 (prod + every client).** The migration
+  registers `AclRecordPermissions` for the new bridge records 317–322 (Core §7 = Super User; Client §6b
+  = per-client copies of the parent record's perms) but **never creates the
+  `AclLogicGroups` → `AclLogicGroupExpressions` → `AclRecordExpressions` chain beneath them.** A 2.0
+  record read requires that full chain (`api2/Component/Api/V2/V2.php`, `!$aclLogicGroupsDefined`), so a
+  role hitting a bridge route (e.g. `item-fulfillment-tracking-numbers`) gets **403 EZ-1** with DEBUG
+  "No ACL Logic Groups defined for ACL Record Permissions". Confirmed in **prod and every client** —
+  working analogs (parent 28, ASN bridges 216/217/218) have 1 logic group + 1 expression each; the IF/IR
+  bridges 317–322 have **0**. Downstream symptom: nested bridge fields return `null` (TOGa Supply's
+  fulfilled-shipments lists shipments but `itemFulfillmentTrackingNumbers` is null → reprint has no
+  label). **Fix:** per bridge `AclRecordPermission`, add one `AclLogicGroup` + `AclLogicGroupExpression` +
+  `AclRecordExpression` (`slug='all'`, `sqlExpression='1'`) — mirroring how 28 / 216 work. Run in **both**
+  `Core` (Super User) **and** each `Client_*` (per-role; `Client_Growrk` fixed on beta this way).
+  **Client-DB caveat:** `Records` is a Core-only table, so the client-side `AclRecordExpressions` insert
+  must derive record ids from `AclRecordPermissions` (`SELECT DISTINCT recordId ... WHERE recordId IN (...)`),
+  **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)
 
 ## Related docs

package/knowledge/2.0/apps/toga2-supply/features/fulfill-and-ship.md

@@ -6,7 +6,7 @@ project: TOGa Supply
 client: shared
 type: feature
 status: active
-updated: 2026-06-10
+updated: 2026-06-16
 owners: [mhammontree]
 files:
   - toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx
@@ -40,7 +40,10 @@ GroWrk, June 2026); FedEx + UPS both need verification before prod.
    **This is the only place the SO syncs from NetSuite into Toga.**
 2. `/edit-shipment` submit (`onFormSubmit("fulfillAndShip")` in `EditShipmentForm.tsx`):
    - `saveShipment` → POST `/item-fulfillments`, `/tracking-numbers`,
-     `/item-fulfillment-packages`.
+     `/item-fulfillment-tracking-numbers` (the bridge — payload key
+     `itemFulfillmentTrackingNumbers`, **not** the old `itemFulfillmentPackages`; see the
+     `_underscore` tracking-number-bridges doc). The frontend migration to the bridge is prod
+     commit `b5c16592d`.
    - `fulfillShipment` → GET `/item-fulfillments/upsShipmentApi` (or `fedexShipmentApi`)
      for the label, then `saveShipmentToNetsuite` →
      GET `/item-fulfillments/createNetsuiteItemFulfillment`.
@@ -91,6 +94,29 @@ likely moves to the backend.
   `hostname LIKE '%ups.com%'`, `responsePayload`).
 - React warning: `setState`-in-render in `ShipmentItemsTable.tsx` (~line 149,
   `clearErrors` inside a `setRowsClicked` updater) — move out of the updater.
+- **Local frontend runs against the *deployed* beta backend.** The dev frontend
+  (`growrk.togasupply:5173`) calls `api.beta.togahub.com`, so **any `_underscore` change
+  only takes effect after a deploy to beta** — a fix you made locally looks "unfixed" until
+  deployed (and a local frontend ahead of the deployed backend produces skew errors, e.g.
+  `Unknown named parameter $labelFileInternalId` when the FE passes a param the deployed
+  method lacks). When chasing a beta error, confirm what commit is deployed before assuming
+  the local code is what ran.
+- **Fulfilled vs pending is driven by `ItemFulfillments.dtSubmitted`** (`ShipmentsApi.ts`
+  `getShipments`: fulfilled = `dtSubmitted ne null`, pending = `eq null`). `dtSubmitted` is
+  set **only** by `createNetsuiteItemFulfillment` on a successful NetSuite IF creation
+  (`Trait/Netsuite/ItemFulfillment.php`). So if the NetSuite step fails, the shipment stays
+  on the **pending** page, never the fulfilled one — "no fulfilled shipments" usually means
+  the NS step didn't complete, not a UI bug.
+- **`createNetsuiteItemFulfillment` line mapping is fragile on partial/already-fulfilled
+  orders.** It `get`s the NetSuite SO and sets the fulfillment `orderLine` = the SO's `line`.
+  If a line is already fulfilled (or NetSuite re-sequences the fulfillable sublist because a
+  line isn't committed), NetSuite returns **"Unable to find a matching line for sublist item
+  with key: [orderLine] and value: [N]"**. Test against an SO line that's genuinely open;
+  robust fix = NetSuite `initialize`/`transform` (only exposes fulfillable lines).
+- **Bridge ACL blocks the tracking/label read (reprint).** Reading tracking via the
+  `item-fulfillment-tracking-numbers` bridge requires the bridge record's ACL logic-group
+  chain to exist for the user's role, or it 403s and `itemFulfillmentTrackingNumbers` returns
+  `null` (so reprint has no label). See the tracking-number-bridges doc's ACL gotcha + fix.
 
 ## Remaining work
 
@@ -112,4 +138,5 @@ not the base `_Model_Client_ItemFulfillment`. Tested with GroWrk; UPS support wa
 for Compass and is not yet in prod.
 
 ## Change history
+- 2026-06-16 — Drove the full beta flow green for UPS/GroWrk. Updated the save step to the `/item-fulfillment-tracking-numbers` bridge (FE commit `b5c16592d`, key `itemFulfillmentTrackingNumbers`). Added gotchas: local-FE↔deployed-beta-BE skew, `dtSubmitted` fulfilled/pending gating, `createNetsuiteItemFulfillment` orderLine fragility on partial/already-fulfilled orders, and the bridge-ACL 403 that nulls tracking/labels (reprint). (mhammontree)
 - 2026-06-10 — Documented the Fulfill & Ship flow (SO sync, label purchase, NetSuite IF creation, success gating, reprint). Driven green on beta for UPS/GroWrk; FedEx + prod verification pending. (mhammontree)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.103",
+  "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",