toga-ai 1.0.327 → 1.0.328

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

@@ -21,7 +21,7 @@
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.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, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql |
 | [Surface Resolver (_Model_Core_Surface::resolve — replaces Page::meta)](features/surface-resolver.md) | The runtime for the platform-wide **Surface** UI presentation layer: 9 `_underscore` models plus a cached resolver, `_Model_Core_Surface::resolve(&$api, string | _underscore/Model/Core/Surface.php, _underscore/Model/Client/AclRecordScript.php, _underscore/Model/Core/RecordScript.php, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Quad/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Client_CompassCanada/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, _underscore/Model/Core/SurfaceElement.php, _underscore/Model/Core/Action.php, _underscore/Model/Core/Vocabulary.php, _underscore/Model/Core/VocabularyTerm.php, _underscore/Model/Core/Message.php, _underscore/Model/Client/SurfaceOverride.php, _underscore/Model/Client/MessageTranslation.php, _underscore/Model/Client/ThemeToken.php, _underscore/Model/Core/Page.php |
-| [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, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19b - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.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, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19b - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Growrk/2026-07-13a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql |
 | [Units for Items for Purchase Orders — Data Structure](features/units-for-items-for-purchase-orders.md) | Describes how unit (serialized inventory) data is linked to sales-order and purchase-order line items behind the `units-for-items-for-purchase-orders` TableView |  |
 | [Refreshing a Local Dev Database from Beta (dev-sandbox)](workflows/local-db-refresh-from-beta.md) | How to reset a local 2.0 dev database from the **beta / dev-sandbox** environment: dump each schema (`Core`, `Client_<Id>`, `Logs_<Id>`, …) from the beta host, | api2/Config/, _underscore/Loader.php, _underscore/Model/Client/BundleTranslation.php, api2/Component/Api/V2/V2.php, toga25-supply/sync_compasscanada_schema.sql |
 | [Running a 2.0 App Locally (browser, end-to-end via api2)](workflows/running-a-2.0-app-locally.md) | The full dependency chain required to run a 2.0 client app **through the browser**, end-to-end, against a **local `api2`** (e.g. | _underscore/Environment.php, _underscore/Config.php, _underscore/Database.php, _underscore/Route.php, api2/Component/Api/V2/V2.php, api2/index.php, api2/.htaccess |

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-02
+updated: 2026-07-14
 owners: [mhammontree]
 files:
   - _underscore/Model/Client/ItemFulfillment.php
@@ -63,12 +63,17 @@ record instead of a hardcoded constant.
   record by UUID, reads its stored raw PNG (`labelPdfFile`), and returns a **combined base64 PDF**
   via `buildFromPngLabels`. Replaced the frontend `pdf-lib` merge (which broke once labels became
   PNG — it expected a base64 PDF). Requires a Client-DB `AclRecordScripts` dispatch grant or it
-  403s — see the ACL permission-chain doc's record-script dispatch section.
+  403s — see the ACL permission-chain doc's record-script dispatch section. **`$caption` accepts a
+  position-aligned CSV** (one caption per uuid, in order) so a combined outbound+return PDF can
+  caption only the return page "Return Label".
 - `_Model_Client_ItemFulfillment::generateReturnLabel(&$api, $uuid)`
-  (`Model/Client/ItemFulfillment.php`): builds a per-carrier **return** shipment request
-  (ship-from = customer, ship-to = warehouse return address; Ground service; FedEx uses drop-off
-  pickup), creates a **second** `TrackingNumbers` record, stores its raw PNG, and links it as
-  `returnTrackingNumberId` on the `ItemFulfillments_TrackingNumbers` header bridge.
+  (`Model/Client/ItemFulfillment.php`): builds a per-carrier **return** shipment request, creates a
+  **second** `TrackingNumbers` record, stores its raw PNG, links it as `returnTrackingNumberId` on
+  the `ItemFulfillments_TrackingNumbers` header bridge, and returns `returnTrackingNumberUuid`. The
+  **return address is now per-fulfillment**: it joins `returnAddressId` → `Addresses`/`States` and
+  ships **from** that saved return address, falling back to the `RETURN_ADDRESS_*` config constants
+  when `returnAddressId` is unset (superseding the earlier fixed `RETURN_ADDRESSES` set). The return
+  leg **reuses the outbound** weight/carrier/method/account (see the return-leg semantic below).
 - `getLabelFormat()` (client UPS config helper): now **defaults to `PNG`** (was ZPL) and validates
   against a supported-format allowlist, so a carrier label reliably comes back as an embeddable PNG.
 - `_Component_Library_Carriers_Ups::submitShipmentRequest`
@@ -117,11 +122,28 @@ reprint combine moved to the backend `reprintLabelsApi` scripted API and return-
 **Return labels.** When `ShipmentRequest->isReturn` is set, the carrier request injects the
 return-service flags: UPS `Shipment.ReturnService.Code = '9'` (Print Return Label); FedEx
 `shipmentSpecialServices.returnShipmentDetail` (`returnType = PRINT_RETURN_LABEL`, RMA reason
-"Customer Return"). `generateReturnLabel` builds the return request with **ship-from = customer,
-ship-to = warehouse**, at **Ground / customer-drops-off** service level (decision), creates a 2nd
-`TrackingNumbers` record, stores its raw PNG, and links `returnTrackingNumberId` on the
-`ItemFulfillments_TrackingNumbers` bridge. Warehouse return addresses come from a `RETURN_ADDRESSES`
-set (two verified addresses: Naperville default + Plainview).
+"Customer Return"). `generateReturnLabel` builds the return request, creates a 2nd
+`TrackingNumbers` record, stores its raw PNG, links `returnTrackingNumberId` on the
+`ItemFulfillments_TrackingNumbers` bridge, and returns `returnTrackingNumberUuid`.
+
+**Return address is now per-fulfillment (2026-07).** `generateReturnLabel` joins
+`ItemFulfillments.returnAddressId` → `Addresses`/`States` and ships **from** that saved return
+address; it falls back to the `RETURN_ADDRESS_*` config constants when `returnAddressId` is unset.
+This supersedes the earlier fixed `RETURN_ADDRESSES` set (Naperville/Plainview).
+
+**Return-leg semantic (important — only the address is independent).** The return leg **reuses the
+outbound shipment's weight/carrier/method/account**: `packageWeightPounds` = the outbound tracking
+weight, and the return `TrackingNumber`'s carrier/method/account = the outbound's. **Only the
+return ADDRESS is persisted** (`returnAddressId`). The TOGa Supply return modal's
+weight/dims/carrier fields are prefilled from outbound **for display only** and are not persisted
+or independently used — see the fulfill-and-ship doc's edit-trap gotcha.
+
+**NetSuite tracking now includes both legs (fixed 2026-07).** `Trait/Netsuite/ItemFulfillment.php::createNetsuiteItemFulfillment`
+read the **retired `itemFulfillmentPackages`** (absent post-bridge), so **no tracking reached
+NetSuite** at all. It now iterates the `itemFulfillmentTrackingNumbers` bridge and pushes the
+**outbound** tracking plus, when present, the **return** tracking as a **second package**
+(`packageDescr = 'Return Label'`). (The 2026-06-16 bridge repoint fixed the four queries in
+`Model/Client/ItemFulfillment.php`; this trait method was a separate straggler on the same table.)
 
 ## `FIELD_STORAGE` mechanics (reference)
 
@@ -222,11 +244,22 @@ still discards the unsaved in-memory value.
   on the tracking record itself must be CIE-enabled.
 - **FedEx credentials are hardcoded in `Fedex.php` and were intentionally retained** (Mark's
   decision) — do not "fix" them into config as part of unrelated work.
+- **Local live-UPS carrier testing setup (local-only).** With `debug_mode=1` the `_underscore` UPS
+  carrier hits the UPS **CIE test** endpoint (`wwwcie.ups.com`). To fulfill locally you need three
+  things or the call fails in confusing ways: (a) `ShippingMethods.code` populated (UPS service
+  codes: Ground=`03`, Next Day Air=`01` — passed straight through as the UPS service `Code`); (b) a
+  **`[ups]` config group with OAuth creds** (`oauth_client_id`/`oauth_client_secret`) **in the dev
+  INI** — without it, it falls back to blank legacy creds and UPS returns **"Invalid Access License
+  number"** (document *where* the creds live, never the values); (c) a **CIE-valid shipper number** —
+  the client's production UPS account (`8696XA`) is rejected by CIE with "Missing or invalid shipper
+  number". The UPS account-location map lives at the developer's local
+  `shipping_carrier_ups_account_location.md`.
 - **Ship guards (2026-07).** Shipping now **fails fast** if the selected carrier account is empty,
   and **errors if an Item Fulfillment has >1 tracking number** (can't determine which account to
   bill) — expect a hard error rather than a silently-wrong bill in those cases.
 
 ## Change history
+- 2026-07-14 — TRUE-79191 return-label increment: `generateReturnLabel` ships from the **per-fulfillment** return address (`returnAddressId` → Addresses/States, falling back to `RETURN_ADDRESS_*`; supersedes the fixed `RETURN_ADDRESSES` set) and returns `returnTrackingNumberUuid`; documented the return-leg reuse semantic (return reuses outbound weight/carrier/method/account — only the address is independent). Fixed `Trait/Netsuite/ItemFulfillment.php::createNetsuiteItemFulfillment`, which read the retired `itemFulfillmentPackages` so no tracking reached NetSuite — now iterates the `itemFulfillmentTrackingNumbers` bridge and pushes outbound + return (2nd package, `packageDescr='Return Label'`). `reprintLabelsApi` `$caption` now accepts a position-aligned CSV for per-page captions. Added the local live-UPS testing setup gotcha (`[ups]` OAuth config, CIE endpoint/shipper, `ShippingMethods.code`). (mhammontree)
 - 2026-07-02 — Reprint combine moved to the backend: new `_Model_Client_TrackingNumber::reprintLabelsApi` scripted API (RecordScript `GET /v2/tracking-numbers/reprint`) returns a combined base64 PDF from the stored PNGs (frontend `pdf-lib` merge removed). Added return-label generation (`generateReturnLabel`; UPS ReturnService `9` / FedEx `PRINT_RETURN_LABEL`; Ground/customer-drops-off; `RETURN_ADDRESSES`; links `returnTrackingNumberId`). Carrier billing account threaded from the tracking record (`shippingCarrierAccountNumber`) — removed `SHIPPER_NUMBER`/`ACCOUNT_NUMBER` constants, fail-fast on empty account, error on >1 tracking number per IF. Ship-to now `COALESCE(IF, SO)` address. `getLabelFormat()` defaults PNG + allowlist. Fixed two SQL injections (`postPost` `$payload->uuid`, `fulfill` NetSuite `$internalId`) and removed leftover debug `echo`/`print_r` from `fulfill()`. Found + fixed the framework-core root cause of storage writes silently vanishing (two `Model.php` `FIELD_STORAGE` bugs — see FIELD_STORAGE mechanics). (mhammontree)
 - 2026-06-18 — Implemented the label-storage rework: request PNG from UPS/FedEx, store the raw PNG, generate the printable PDF on demand via the new `_Component_Library_LabelPdf` (FPDF); dropped Labelary. Added the FedEx tracking-cred config-fallback fix and the `_Loader`→Composer FPDF autoloader toggle. Open: the `labelPdfFile` S3 write still skips on a lazy-model save. (mhammontree)
 - 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)

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-09
+updated: 2026-07-14
 owners: ["jcardinal", "mhammontree", "dfranks", "apeterson"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -23,6 +23,7 @@ files:
   - dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql
   - dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql
   - dbchanges2/Client_Nychh/2026-06-19b - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql
+  - dbchanges2/Client_Growrk/2026-07-13a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql
   - dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql
   - dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql
 related:
@@ -153,8 +154,13 @@ returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTracki
     integrations enabled 403s (EZ-1) on the bridge records the moment the sync exercises them. Fixed one-off
     per client as each starts failing: **Prudential** (`Client_Prudential/2026-06-15 - ...`, recs 317/319) and
     **Quad** (`Client_Quad/2026-06-18a - ...`, all of 317-322) and **NYCHH**
-    (`Client_Nychh/2026-06-19b - ...`, all of 317-322) so far. Each new client is whack-a-mole until
-    the chain is folded back into the base migration + blank-client template.
+    (`Client_Nychh/2026-06-19b - ...`, all of 317-322) and **GroWrk**
+    (`Client_Growrk/2026-07-13a - ...`, all of 317-322) so far. Each new client is whack-a-mole until
+    the chain is folded back into the base migration + blank-client template. **Decision (Mark,
+    TRUE-79191):** the GroWrk fix is kept **Client_Growrk-scoped** for now — GroWrk is (as far as
+    told) the only client on Fulfill & Ship and the team pattern is per-client anyway. A shared
+    `Client/` migration would fix all clients at once if the feature broadens — that remains the
+    preferred long-term fix (fold into the base migration + blank-client template).
 
 - **`Client_CompassCanada` is missing these bridge tables on *beta* (local drift).** Beta's
   `Client_CompassCanada` lacks 17 tables that prod has — including the `*_TrackingNumbers`
@@ -167,6 +173,7 @@ returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTracki
 - **Porting the item-fulfillment TableView fix to another client is two independent decisions, not a copy-paste.** The **re-root** (Units 31 → ItemFulfillmentItems 29 + OUTER unit chain) is universally portable and fixes the "0 records" bug everywhere. The **tracking source is client-specific**: Compass writes one tracking number per item fulfillment at the **item level (318)**, so its views read 318. Other clients populate different bridge levels — verify with `SELECT COUNT(*)` per bridge before choosing. As of 2026-06-19, **record 318 is empty in `Client_Nychh` and `Client_Quad`**; their tracking lives at the **IF/shipment level (317)** (covers IFIs: NYCHH 7955/10049 ≈ 79%, Quad 4878/4967 ≈ 98%) and the **unit level (319)** (≈ 7–9% — serialized only). Copying Compass's 318 join into a client that doesn't write 318 yields a structurally-correct view with permanently blank tracking until 318 is backfilled. (NYCHH's pre-fix view pointed at the now-deleted record 41 = old IF-level/package bridge, i.e. it originally intended IF-level 317.)
 
 ## Change history
+- 2026-07-14 — **GroWrk** hit the bridge ACL gap (TRUE-79191): 403 EZ-1 on `item-fulfillment-tracking-numbers` made TOGa Supply's Pending Shipments list come back `isSuccess:false` (frontend showed the empty "Create your first shipment" state). GroWrk never got the fix that Prudential (2026-06-15) and Quad (2026-06-18a) already had. Added `Client_Growrk/2026-07-13a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql` (all 6 bridges 317-322, idempotent NOT-EXISTS guards, `slug='all'`/`sqlExpression='1'`, root logic group operator AND). Decision: kept Growrk-scoped for now (only client on Fulfill & Ship); shared `Client/` migration remains the long-term fix. (mhammontree)
 - 2026-07-09 — Noted that `Client_CompassCanada` is missing these bridge tables on **beta**, so a local
   reset from beta reintroduces the 17-table drift (1146 on SalesOrders load); fix locally with
   `sync_compasscanada_schema.sql`. Cross-linked the new local-DB-refresh-from-beta workflow. (apeterson)

package/knowledge/2.0/apps/api2/workflows/codepipeline-codeconnections-deploy.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: workflow
 status: active
-updated: 2026-06-18
+updated: 2026-07-14
 owners: ["jcardinal", "mhammontree"]
 files: []
 related: []
@@ -20,6 +20,16 @@ the `agilantsolutions` org. A single pipeline can have multiple Source actions s
 connection (e.g. `agilantsolutions/api2` and `agilantsolutions/_underscore` on the same
 connection ARN). Deployment target is Elastic Beanstalk.
 
+## Branch model (which branch deploys where)
+The application repos (`_underscore`, `api2`, `toga2-supply`) deploy from **long-lived per-env
+branches** — `_beta`, `_production` (and `_stage`, etc.) — not from `_main`. **api2 pulls
+`_underscore`'s matching `_<env>` branch at EB build time**, so promoting a shared `_underscore`
+change to an env means merging it into that `_underscore` `_<env>` branch (the api2 build then
+picks it up). **`dbchanges2` has only `_main`** — its migrations are applied **per-environment by
+the team's process**, decoupled from the app branches; a code deploy does not run migrations. So a
+full feature promotion to an env = apply the `dbchanges2` migrations to that env **and** deploy the
+app-repo `_<env>` branches.
+
 ## Steps
 1. A push to the watched branch (e.g. `_stage`) triggers the pipeline.
 2. The Source stage uses `CodeStarSourceConnection` actions, each referencing:
@@ -103,6 +113,7 @@ aws codeconnections get-connection --connection-arn "<CONN_ARN>" --region "$REGI
 ```
 
 ## Change history
+- 2026-07-14 — Documented the branch model: app repos (`_underscore`/`api2`/`toga2-supply`) deploy from long-lived `_beta`/`_production` branches (not `_main`); api2 pulls `_underscore`'s `_<env>` branch at EB build; `dbchanges2` has only `_main` and its migrations are applied per-env by the team process (not by a code deploy). (mhammontree)
 - 2026-06-18 — Added two EB-instance gotchas surfaced during the TOGa Supply beta/prod label deploys: (1) terminated instances must be **manually re-registered** as LB targets (we don't pay for auto-registration) — until then the new code never serves traffic and looks like deploy-lag; (2) on-instance `composer require` stopgap syntax (no space after the colon, fix root cause by committing `composer.lock`). (mhammontree)
 - 2026-06-16 — Documented after a pipeline (API-QC-Security, account 975050298201) failed every
   run at Source with "[GitHub] GitHub returned an Internal Error"; connection was AVAILABLE and

package/knowledge/2.0/apps/toga2-supply/INDEX.md

@@ -3,5 +3,5 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [TOGa Supply (toga2-supply) Architecture](architecture.md) | `toga2-supply` is the **React + Vite frontend** for TOGa Supply — warehouse fulfillment tooling (shipment selection, fulfill & ship against carrier APIs, NetSui | toga2-supply/src/api/toga.ts, toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx |
-| [Fulfill & Ship](features/fulfill-and-ship.md) | Fulfill & Ship lets a warehouse user select sales-order line items, enter serials, pick a carrier/method, and in one action: create the Item Fulfillment records | toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/Shipments/view/ShipmentsPage.tsx, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, toga2-supply/src/pages/FulfilledShipments/view/FulfilledShipmentsPage.tsx, _underscore/Model/Client/ItemFulfillment.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php |
+| [Fulfill & Ship](features/fulfill-and-ship.md) | Fulfill & Ship lets a warehouse user select sales-order line items, enter serials, pick a carrier/method, and in one action: create the Item Fulfillment records | toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx, toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/pages/EditShipment/view/components/SelectedShipmentItemsTable.tsx, toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/EditShipment/types.ts, toga2-supply/src/pages/Shipments/view/ShipmentsPage.tsx, toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx, toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts, toga2-supply/src/pages/Shipments/types.ts, toga2-supply/src/pages/FulfilledShipments/view/FulfilledShipmentsPage.tsx, toga2-supply/src/components/ui/CardTable/CardTable.tsx, toga2-supply/src/components/ui/CardTable/types.ts, toga2-supply/src/assets/pen-line.svg, _underscore/Model/Client/ItemFulfillment.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php |
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-supply` (React + Vite) builds and deploys on **AWS Amplify**. | toga2-supply/amplify.yml, toga2-supply/.gitattributes, toga2-supply/.github/workflows/sync-stage-environments.yml, toga2-supply/.env.qc-security |

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

@@ -6,17 +6,24 @@ project: TOGa Supply
 client: shared
 type: feature
 status: active
-updated: 2026-07-02
+updated: 2026-07-14
 owners: [mhammontree]
 files:
   - toga2-supply/src/pages/ShipmentItems/view/ShipmentItemsPage.tsx
   - toga2-supply/src/pages/EditShipment/view/EditShipmentPage.tsx
   - toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx
+  - toga2-supply/src/pages/EditShipment/view/components/SelectedShipmentItemsTable.tsx
+  - toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx
   - toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts
+  - toga2-supply/src/pages/EditShipment/types.ts
   - toga2-supply/src/pages/Shipments/view/ShipmentsPage.tsx
   - toga2-supply/src/pages/Shipments/view/components/ShipmentsCardTableForm/ShipmentsCardTableForm.tsx
   - toga2-supply/src/pages/Shipments/api/ShipmentsApi.ts
+  - toga2-supply/src/pages/Shipments/types.ts
   - toga2-supply/src/pages/FulfilledShipments/view/FulfilledShipmentsPage.tsx
+  - toga2-supply/src/components/ui/CardTable/CardTable.tsx
+  - toga2-supply/src/components/ui/CardTable/types.ts
+  - toga2-supply/src/assets/pen-line.svg
   - _underscore/Model/Client/ItemFulfillment.php
   - _underscore/Trait/Netsuite/ItemFulfillment.php
   - _underscore/Component/Library/Carriers/Ups/Ups.php
@@ -59,6 +66,27 @@ GroWrk, June 2026); FedEx + UPS both need verification before prod.
    `saveShipmentToNetsuite` → `createNetsuiteItemFulfillment`, which attaches the label
    to the IF **after** creating it (the IF doesn't exist yet when the label is bought).
 
+## Edit a saved (unfulfilled) pending shipment in place (2026-07)
+
+A saved-but-not-yet-fulfilled shipment can now be **edited in place** rather than only
+re-created. Pending Shipments (`ShipmentsCardTableForm`, non-fulfilled view) shows an edit
+pencil (`src/assets/pen-line.svg`, tinted `supply-blue-400` to match the trash icon) **only**
+on rows where `dtSubmitted == null` (i.e. not yet pushed to NetSuite). Clicking it opens the
+Edit Shipment form at `/edit-shipment?internalId=<so>&itemFulfillmentUuid=<uuid>`, rehydrated
+from the saved fulfillment; **Save UPDATES the existing records** instead of POSTing a new draft.
+
+- `getShipmentForEdit(uuid)` (`UpdateShipmentApi.ts`) loads the tracking fields + uuid,
+  ship-to + return addresses + their uuids, and item lines with unit serials.
+- `updateShipment()` PUTs `/tracking-numbers/{uuid}`, PUTs `/addresses/{shipToUuid}`, and PUTs
+  the existing return address (or creates + links one). It returns the **same shape** as
+  `saveShipment`, so the downstream fulfill/label/print flow is unchanged.
+- **v1 scope (decision, Mark):** shipment details + ship-to address + return label/address are
+  editable; **item lines & serial numbers are READ-ONLY**. `SelectedShipmentItemsTable` gained a
+  `readOnly` prop that renders serials as text, and the "all serials provided" button-enable gate
+  is auto-satisfied in edit mode.
+- `CardTable` was made reusable for this: optional `editIcon` + `isEditButtonDisabled` props
+  (defaults preserve prior behavior; the shipments card is the only consumer today).
+
 ## Reprint (backend-combined, 2026-07)
 
 Fulfilled-shipments view (`FulfilledShipmentsPage` → `ShipmentsCardTableForm` with
@@ -126,6 +154,19 @@ the call 403s and returns no label.
   `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.
+- **Return modal's non-address fields are an edit-trap (not persisted, not used).** On the
+  backend the return leg **reuses the outbound shipment's weight/carrier/method/account**
+  (`generateReturnLabel`: `packageWeightPounds` = outbound tracking weight; the return
+  `TrackingNumber`'s carrier/method/account = outbound). **Only the return ADDRESS is persisted**
+  (`returnAddressId`). The return modal's weight/dims/carrier fields are prefilled from the
+  outbound shipment **for display only** — editing them changes nothing. Follow-up: make those
+  fields read-only OR persist independent return dimensions.
+- **Declared Cost column showed a constant "$ -" on Pending Shipments (fixed 2026-07).** The
+  column + formatter existed, but `getShipments` (`ShipmentsApi.ts`) never *requested*
+  `trackingNumber.declaredCost` and the card row-builder (`ShipmentsCardTableForm.tsx`) never
+  mapped it into `flattenedData`. Added the field to the query and the row map (+ `declaredCost`
+  on the `FlattenedData` type). A missing column that always renders empty is usually a
+  not-requested / not-mapped field, not a formatter bug.
 - **Two separate page components + a scroll/clip trap.** `/shipments` renders `ShipmentsPage`;
   `/fulfilled-shipments` renders `FulfilledShipmentsPage` — **separate components** (a fix to one
   does NOT touch the other; the shared list is `ShipmentsCardTableForm`). Both pages used
@@ -143,14 +184,42 @@ the call 403s and returns no label.
 
 - ~~Reprint rewire~~ — done (backend `reprintLabelsApi` combine; see Reprint section).
 - ~~Address-source decision~~ — done (`COALESCE(IF, SO)`).
-- Return-label flow: backend generation is done (`generateReturnLabel`; UPS ReturnService `9` /
-  FedEx `PRINT_RETURN_LABEL`; 2nd tracking number linked via `returnTrackingNumberId` on the
-  bridge; Ground/customer-drops-off). Remaining **frontend** polish: "needs return label" control,
-  a return-address editable combo ("Rolodex pattern" of client locations, overridable, validated),
-  and "return label" text on return pages of the combined PDF.
+- ~~Return-label flow (Increment 3)~~ — **done end-to-end (2026-07).** Backend `generateReturnLabel`
+  now ships FROM the per-fulfillment return address (`returnAddressId` → Addresses/States, falling
+  back to the `RETURN_ADDRESS_*` config), and the frontend fulfill flow (`UpdateShipmentApi.ts`
+  `fulfillShipment(needsReturnLabel)` + `EditShipmentForm.tsx`) prints one **combined outbound +
+  return PDF**, with the return page captioned "Return Label" (`ShipmentsApi.ts` passes a
+  position-aligned `captions` CSV to `reprintLabelsApi`). See the carrier-shipping-labels doc.
+- **Edit-mode follow-ups (v1 punts):** (a) serial-number editing in edit mode — would need
+  unit add/remove diffing against the API (the edit route already carries the fulfillment uuid);
+  (b) the return modal's weight/dims/carrier fields are an **edit-trap** — see the gotcha below.
 - UPS 35-char hardening, location-scoped inventory lookup, carrier/method on the NS IF,
   responsiveness per Figma, FedEx + UPS end-to-end verification before prod.
 
+## Deploy / provisioning requirements (per environment)
+
+The return-label feature (TRUE-79191) needs **four** things present in a given environment or it
+silently mis-behaves; treat these as the release checklist when promoting to a new env:
+1. **`ItemFulfillments.returnAddressId` column** (Client DB) — the persisted return address FK.
+2. **RecordField 2434** (Core) — the record field backing `returnAddressId`.
+3. **`generateReturnLabel` RecordScript** (Client DB) — the scripted-API dispatch grant.
+4. **Bridge ACL logic groups for records 317–322** (Client DB) — or reads 403 EZ-1; see the
+   tracking-number-bridges doc.
+
+**Environment status snapshot (2026-07, TRUE-79191):** GroWrk is **not** in the beta cluster; it
+exists non-prod only in **dev-sandbox** (closest to ready: has the bridge, bridge ACL logic
+groups, and the `generateReturnLabel` RecordScript, but is **missing** the `returnAddressId`
+column and RecordField 2434) and **client-sandbox** (far behind — no bridge at all), plus prod.
+**Prod is not migrated for this feature** (missing `returnAddressId`, RecordField 2434, the
+`generateReturnLabel` RecordScript, and all six bridge ACL logic groups — the 403 gap is live in
+prod now).
+
+**"Testing in prod" (PMO Aaron's call, since no client uses the feature yet) is a FULL prod
+release, not a sandbox run.** It means applying all TRUE-79191 `dbchanges2` migrations to prod +
+deploying code to `_production`; a live run then buys a **REAL** UPS label on Agilant account
+`8696XA` (prod endpoint) and creates a **REAL** NetSuite Item Fulfillment. Plan to **void the
+labels and reverse the fulfillment** afterward.
+
 ## Client variations
 
 None in the flow itself — but the NetSuite trait is composed into **client-specific**
@@ -159,6 +228,7 @@ not the base `_Model_Client_ItemFulfillment`. Tested with GroWrk; UPS support wa
 for Compass and is not yet in prod.
 
 ## Change history
+- 2026-07-14 — TRUE-79191: added **edit-a-saved-pending-shipment-in-place** (pencil on `dtSubmitted==null` rows → `/edit-shipment`, `getShipmentForEdit`/`updateShipment` PUT existing records; item lines/serials read-only in v1; `CardTable` made reusable with `editIcon`/`isEditButtonDisabled`). Completed the Increment-3 **return-label** frontend (combined outbound+return PDF, return page captioned "Return Label" via a position-aligned `captions` CSV to `reprintLabelsApi`). Fixed the Declared Cost "$ -" column (field was never requested/mapped). Documented the return-modal edit-trap (only the return ADDRESS persists — weight/carrier/dims reuse outbound) and the per-env deploy/provisioning checklist + the "testing in prod = full prod release (real labels/NS IF)" decision. (mhammontree)
 - 2026-07-02 — Reprint rewired to the backend: `ShipmentsApi.ts` now calls `GET /v2/tracking-numbers/reprint` (`reprintLabelsApi`) for a combined base64 PDF built from the stored PNGs; removed the stale client-side `pdf-lib` merge. Return-label backend generation landed (`generateReturnLabel`, `returnTrackingNumberId` on the bridge). Ship-to address source resolved to `COALESCE(IF, SO)`. (mhammontree)
 - 2026-06-18 — PNG label-storage rework reflected on the frontend: labels now store as PNG and the PDF is built on the backend (`LabelPdf`), so the client-side `pdf-lib` reprint is stale and must be rewired to a backend generate endpoint. Fixed the Fulfilled Shipments responsiveness/clip bug (Reprint button unreachable at 100% zoom) — `overflow-scroll` → `overflow-auto` and gave `FulfilledShipmentsPage`'s outer its own scroll; documented the `/shipments` vs `/fulfilled-shipments` two-component trap and the `AuthLayout overflow-hidden` clip. (mhammontree)
 - 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)

package/knowledge/clients/growrk/profile.md

@@ -5,13 +5,14 @@ apps:
   - _underscore
   - api2
   - worker2
+  - toga2-supply
   - dbchanges2
 project: _Underscore
 client: growrk
 type: profile
 status: active
-updated: 2026-06-19
-owners: ["rgirish"]
+updated: 2026-07-14
+owners: ["rgirish", "mhammontree"]
 files: []
 related:
   - clients/growrk/features/transfer-order-flow.md
@@ -20,3 +21,9 @@ related:
 ## Summary
 
 GroWrk is a 2.0 client using TOGA for inventory and order management. Their primary integration involves inventory movements between locations (warehouses, distribution points). NetSuite is the ERP. The key engineering challenge is that GroWrk historically used zero-dollar SalesOrders with holdInvoice=true in NetSuite as a workaround to represent internal inventory transfers — work is underway to replace this with a dedicated TransferOrders record type in the TOGA DB while keeping NetSuite unchanged.
+
+GroWrk is (as far as told) the **only client on TOGa Supply's Fulfill & Ship** flow — it is the client used to drive that feature and its return-label increment (TRUE-79191) green. See the [Fulfill & Ship feature](../../2.0/apps/toga2-supply/features/fulfill-and-ship.md) and [tracking-number bridges](../../2.0/apps/_underscore/features/tracking-number-bridges.md).
+
+## Local dev gotchas
+
+- **`_Model_Growrk_Unit` declares runtime custom-field columns that must physically exist on `Client_Growrk.Units`.** The model declares `c_` fields (`c_itemDescription`, `c_chargingBrick`, `c_deviceStatus`, `c_chargingCable`, `c_grade`); these are runtime custom-field columns, so a locally-drifted `Client_Growrk` DB missing them **1054s (unknown column) on any Unit load**. Add the columns to bring a local DB current.

package/package.json

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