toga-ai 1.0.102 → 1.0.104

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

@@ -6,4 +6,4 @@
 | [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 |
 | [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/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,25 @@ 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 — 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/knowledge/INDEX.md

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 4 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 5 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 6 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **togadesk** (TOGa Desk) — 7 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 5 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 - **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)
@@ -14,7 +14,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 6 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 7 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 6 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)

package/knowledge/clients/prudential/INDEX.md

@@ -3,5 +3,6 @@
 | 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: Service Request Regional Address Validation](features/service-request-address-validation.md) | 2.0 | The `prePost` interceptor on `_Model_Prudential_ServiceRequest` validates `deliverToAddress` fields differently depending on which Prudential regional customer | _underscore/Model/Prudential/ServiceRequest.php |
 | [Prudential Financial](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`). |  |
 | [Prudential: Dell ASN failed POST backfill replay](workflows/dell-asn-backfill-replay.md) | 2.0 | When Dell ASN POSTs fail in bulk (e.g. |  |

package/knowledge/clients/prudential/features/service-request-address-validation.md

@@ -0,0 +1,101 @@
+---
+title: "Prudential: Service Request Regional Address Validation"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: prudential
+type: client-feature
+status: active
+updated: 2026-06-16
+owners: ["rgirish"]
+files:
+  - _underscore/Model/Prudential/ServiceRequest.php
+related:
+  - clients/prudential/profile.md
+  - clients/prudential/features/dell-asn-units-interceptor.md
+---
+
+## Summary
+
+The `prePost` interceptor on `_Model_Prudential_ServiceRequest` validates `deliverToAddress`
+fields differently depending on which Prudential regional customer is placing the request.
+The region is determined at runtime by looking up `customer.uuid` (sent in the POST payload)
+against the `Client_Prudential.Customers` table, whose `name` column holds the region label.
+Three regions are supported: **USA**, **India**, **Ireland**. Unknown or absent UUIDs fall
+back to USA rules.
+
+## Key files / entry points
+
+- `_underscore/Model/Prudential/ServiceRequest.php` — `prePost` interceptor; private methods
+  `resolveRegion()`, `validateUsaAddress()`, `validateIndiaAddress()`, `validateIrelandAddress()`
+
+## How it works
+
+1. `prePost` fires before each POST to `/v2/service-requests` for the Prudential client.
+2. `resolveRegion()` reads `payload->customer->uuid`, escapes it, and queries
+   `Client_Prudential.Customers` for the matching `name`. Returns `'India'`, `'Ireland'`, or
+   `'USA'` (default for anything unrecognised or when uuid is null).
+3. A `match` expression dispatches to the correct validator.
+4. On any validation failure, an `Exception` is thrown with a semicolon-delimited list of all
+   errors — the API engine catches it and returns a 4xx to Dell.
+
+## Data model
+
+`Client_Prudential.Customers` — the region lookup table:
+
+| Column | Type      | Notes                                              |
+|--------|-----------|----------------------------------------------------|
+| `id`   | int PK    |                                                    |
+| `uuid` | char(36)  | Sent by Dell in `customer.uuid` on every POST       |
+| `name` | varchar   | Region label: `'USA'`, `'India'`, or `'Ireland'`   |
+
+## Validation rules by region
+
+### USA (default)
+| Field                  | Rule                                      |
+|------------------------|-------------------------------------------|
+| `line1`                | Required, max 35 chars                    |
+| `line2`                | Optional, max 35 chars                    |
+| `city`                 | Required                                  |
+| `zip`                  | Required (any characters)                 |
+| `state.code`           | Required, exactly 2 alphabetic characters |
+
+### India (Dell India primary field spec)
+| Field             | Rule                                                  |
+|-------------------|-------------------------------------------------------|
+| `line1`           | Required, max 30 chars (Customer/Consignee Name)      |
+| `line2`           | Optional, max 30 chars (Address Line 1)               |
+| `line3`           | Optional, max 30 chars (Address Line 2)               |
+| `city`            | Required, max 30 chars (Address Line 3 / city)        |
+| `zip`             | Required, max 6 chars, strictly numeric (0–9)         |
+| `mobileNumber`    | Optional, 10–15 chars, numeric                        |
+| `telephoneNumber` | Optional, 6–15 chars, numeric                         |
+| `customerCode`    | Optional, max 6 chars, alphanumeric                   |
+| `originAreaCode`  | Optional, max 3 chars, alphabetic (A–Z)               |
+
+India optional fields (`mobileNumber`, `telephoneNumber`, `customerCode`, `originAreaCode`)
+are silently skipped when absent — Prudential has not yet started sending them.
+
+### Ireland
+Same as USA except `zip` accepts any characters — Irish Eircode format is alphanumeric
+with a space (e.g. `F92 FP83`). No numeric restriction.
+
+## Gotchas / known issues
+
+- **Null UUID = USA fallback.** All requests sent before Prudential added `customer.uuid` to
+  their payload lacked the field entirely; those are treated as USA and pass through unchanged.
+  This is intentional backward compatibility.
+- **Region check is by `Customers.name` string, not by id.** If the customer name is ever
+  changed in the DB (e.g. `'USA'` → `'United States'`), the validator will silently fall
+  back to USA rules for all regions. The match arms are `'India'` and `'Ireland'` only;
+  everything else maps to USA.
+- **India optional fields are forward-compatible.** The Dell India field spec includes
+  `mobileNumber`, `telephoneNumber`, `customerCode`, and `originAreaCode` but Prudential has
+  not started sending them yet. The validators already handle them — no code change needed
+  when Prudential starts including them.
+- **`line3` is India-only.** USA and Ireland validators do not check `line3` (it is not in
+  their Dell spec). If Dell starts sending it for USA/Ireland it is silently ignored.
+
+## Change history
+- 2026-06-16 — Created: regional address validation (USA/India/Ireland) replacing the single
+  USA-only `validateDeliverToAddress` method; region resolved from `customer.uuid` lookup (rgirish)

package/knowledge/clients/prudential/profile.md

@@ -9,11 +9,12 @@ project: _Underscore
 client: prudential
 type: profile
 status: active
-updated: 2026-06-10
-owners: ["jcardinal"]
+updated: 2026-06-16
+owners: ["jcardinal", "rgirish"]
 files: []
 related:
   - features/dell-asn-units-interceptor.md
+  - features/service-request-address-validation.md
 ---
 
 ## Summary
@@ -24,7 +25,10 @@ return-tracking per unit) into the 2.0 platform (DB `Client_Prudential`); the 1.
 order-status transmissions.
 
 ## Integrations
-- **Inbound:** Dell API → POST `/v2/advance-shipping-notices` (creates ASNs + units + tracking).
+- **Inbound (ASNs):** Dell API → POST `/v2/advance-shipping-notices` (creates ASNs + units + tracking).
+- **Inbound (Service Requests):** Dell API → POST `/v2/service-requests`. Payload includes
+  `customer.uuid` which maps to a regional customer record (`USA`, `India`, or `Ireland`) in
+  `Client_Prudential.Customers` — used to apply region-specific `deliverToAddress` validation.
 - **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`.
@@ -32,6 +36,8 @@ order-status transmissions.
 ## 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.
+- Service request region is resolved from `Customers.name` string (`'USA'`/`'India'`/`'Ireland'`).
+  Renaming those customer records in the DB would silently break regional validation routing.
 
 ## Related docs
 - Dell ASN units interceptor.

package/package.json

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