toga-ai 1.0.362 → 1.0.364

package/knowledge/2.0/apps/_underscore/features/acl-permission-chain.md

@@ -112,6 +112,30 @@ Worked example: the reprint API `GET /v2/tracking-numbers/reprint`
 Client-DB `AclRecordScripts` grant (migrations in `dbchanges2`) before it stopped 403ing — see the
 carrier-shipping-labels feature doc.
 
+## Add a writable field to a V2 record (3-file migration)
+
+Adding a persisted, API-writable field to an existing V2 record is a **three-file migration set**
+— miss any one and the API rejects the write with a specific code (see the
+[V2 API error codes](../../api2/features/v2-api-error-codes.md) map):
+
+1. **Core `RecordFields` registration** (`dbchanges2/Core/`) — register the field name + type
+   (e.g. `'STRING'`) against the record. Resolve the `recordId` by **route**, not a hardcoded id.
+   **Without it the API returns `EV-8`** ("field does not exist").
+2. **Client column** (`dbchanges2/Client/`) — `ALTER TABLE <Table> ADD <field> <type>`, guarded
+   by an `INFORMATION_SCHEMA` existence check so it is safe to replay and safe against the
+   `BLANK_CLIENT_DATABASE` template.
+3. **Client `AclFieldPermissions` grant** (`dbchanges2/Client/`) — grant the caller's role(s)
+   read/write on the new field. **Without it the API returns `EV-9`** ("no permission to write
+   field"). The reliable way to get the right rows is to **clone the grants of an existing
+   writable sibling field** on the same record — pick a sibling that actually has explicit
+   `AclFieldPermissions` rows (e.g. on `TrackingNumbers`, `containsBattery` has them, whereas
+   `requiresSignature` had none), and resolve `roleId` by subselect.
+
+Worked example (TRUE-79191, `TrackingNumbers.signatureType`): `Core/... - TrackingNumberSignatureTypeRecordField.sql`
+(RecordField, `STRING`), `Client/... - TrackingNumberSignatureType.sql` (guarded `ALTER TABLE`),
+`Client/... - TrackingNumberSignatureTypeFieldPermission.sql` (cloned `containsBattery`'s grants).
+This mirrors the earlier `needsReturnLabel` / `returnAddressId` 3-file sets.
+
 ## Checklist (so the chain is never half-built)
 
 - [ ] `AclRecordPermissions` row for the role × record with the right CRUD flags.
@@ -123,6 +147,10 @@ carrier-shipping-labels feature doc.
 
 ## Change history
 
+- **2026-07-17** — TRUE-79191: added the **"add a writable field to a V2 record" 3-file migration**
+  recipe (Core `RecordFields` → `EV-8` if missing; guarded Client column; Client `AclFieldPermissions`
+  → `EV-9` if missing, cloned from a writable sibling like `containsBattery`), worked example
+  `TrackingNumbers.signatureType`. Cross-linked the new V2 API error-codes map. (mhammontree)
 - **2026-07-02** — Added the record-script dispatch grant (`AclRecordScripts`) as a gate distinct
   from the record-CRUD chain, with the full recipe for exposing a scripted API on a `_Model`
   (Core.RecordScripts route + Client `AclRecordScripts` grant + `(&$api, …)` method), discovered

package/knowledge/2.0/apps/_underscore/features/address-validation.md

@@ -53,6 +53,24 @@ scripted endpoint in **`Core.RecordScripts`** (id 17: `recordId` 13 = Addresses,
   route = validateAddress) returns to **`data.addresses.validateAddress`**, which is exactly
   what the frontend reads.
 
+## `GET /addresses/validate` — the migration-registered route (2026-07)
+
+TRUE-79191 added a **second** route to the same `validateAddress` PHP method, this time **registered
+in `dbchanges2` source** (closing the parity gap noted below) rather than only in the live DB:
+
+- **Route** — `Core.RecordScripts` row: `recordId` = Addresses, `method` `GET`, route **`validate`**,
+  `phpMethod` `validateAddress` (`dbchanges2/Core/2026-07-16b - AddressValidateRecordScript.sql`).
+- **Dispatch grant** — Client `AclRecordScripts` grant to roles **Public (1) / Super User (3) /
+  Base (4)** (`dbchanges2/Client/2026-07-16c - AddressValidateScriptAcl.sql`). Without it the call
+  403s with `EZ-1`.
+- **Response path** — because the route is `validate`, the result lands at
+  **`data.addresses.validate`** (the Fulfill & Ship return-address modal reads exactly this;
+  distinct from the older global `validateAddress` route's `data.addresses.validateAddress`).
+
+The PHP method (`_Model_Client_Address::validateAddress`) already existed and was unchanged — it was
+simply **unrouted in source** until this migration set exposed it. New scripted routes should follow
+this pattern (route + `AclRecordScripts` both in `dbchanges2`).
+
 ## Client variations
 
 None — this is shared engine + framework behavior. The carrier credentials are resolved
@@ -68,6 +86,11 @@ per the standard client carrier config.
 
 ## Change history
 
+- 2026-07-17 — TRUE-79191: added a **`dbchanges2`-registered** `GET /addresses/validate` route to the
+  same `validateAddress` method (Core `RecordScripts` route `validate` + Client `AclRecordScripts`
+  grant to Public/SuperUser/Base) so the Fulfill & Ship return-address modal can validate on save;
+  response at `data.addresses.validate`. Method was pre-existing but unrouted. Closes the source/DB
+  parity gap going forward. (mhammontree)
 - 2026-07-07 — Documented `_Model_Client_Address::validateAddress` (USPS→FedEx→UPS waterfall
   + normalized success shape) and the global `GET /addresses/validateAddress`
   (`Core.RecordScripts` id 17) endpoint, including the dispatch precedence, the

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

@@ -145,6 +145,29 @@ NetSuite** at all. It now iterates the `itemFulfillmentTrackingNumbers` bridge a
 (`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.)
 
+## Signature type on the label (implemented 2026-07)
+
+Signature was **never applied to labels before** — the carrier libs ignored it. Fulfill & Ship now
+carries a **4-level signature type** (None Specified / Indirect / Direct / Adult) end-to-end onto the
+outbound label:
+
+- **Storage & field.** `TrackingNumbers.signatureType` (`VARCHAR(255)`), exposed as
+  `_Model_Client_TrackingNumber::$signatureType = self::FIELD_CHAR` and registered as a Core
+  RecordField + Client `AclFieldPermissions` grant (the 3-file migration — see the ACL doc).
+- **Threading.** A **generic `$signatureType`** field was added to
+  `Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php`. Both outbound paths
+  (`fedexShipmentApi`, `upsShipmentApi` in `Model/Client/ItemFulfillment.php`) now **SELECT
+  `TrackingNumbers.signatureType`** and pass it into the request. **Return-label flows are
+  untouched — no signature on returns.**
+- **FedEx mapping** (`Component/Library/Carriers/Fedex/Fedex.php`): maps the level to per-package
+  `packageSpecialServices.signatureOptionType` → `INDIRECT` / `DIRECT` / `ADULT`. **None Specified
+  is sent explicitly as `NO_SIGNATURE_REQUIRED`.**
+- **UPS mapping** (`Component/Library/Carriers/Ups/Ups.php`): maps to
+  `Package.PackageServiceOptions.DeliveryConfirmation.DCISType` (`2` = Signature Required, `3` =
+  Adult) on **both the OAuth and the legacy payloads**. **⚠ UPS has no Indirect tier — Indirect
+  falls back to Signature Required (`2`).** None Specified is **omitted** (UPS default, no
+  confirmation).
+
 ## `FIELD_STORAGE` mechanics (reference)
 
 `Model.php` handles storage fields separately from regular columns (write loop ~line
@@ -259,6 +282,14 @@ still discards the unsaved in-memory value.
   bill) — expect a hard error rather than a silently-wrong bill in those cases.
 
 ## Change history
+- 2026-07-17 — TRUE-79191: applied **signature type** to outbound labels for the first time (carrier
+  libs previously ignored it). Added a generic `$signatureType` on `ShipmentRequest`;
+  `fedexShipmentApi`/`upsShipmentApi` now SELECT + pass `TrackingNumbers.signatureType`; FedEx maps to
+  `packageSpecialServices.signatureOptionType` (INDIRECT/DIRECT/ADULT, None → explicit
+  `NO_SIGNATURE_REQUIRED`); UPS maps to `DeliveryConfirmation.DCISType` (2=Signature, 3=Adult) on both
+  OAuth + legacy payloads, **Indirect falls back to 2 (UPS has no Indirect tier)**, None omitted.
+  Return-label flows untouched. `TrackingNumbers.signatureType` column + `$signatureType=FIELD_CHAR`
+  added. (mhammontree)
 - 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)

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

@@ -11,5 +11,6 @@
 | [Surface action-state via the surface=<slug> request option (M2M-safe)](features/surface-meta-option.md) | An opt-in V2 engine request option, `surface=<slug>`, that attaches per-record UI action state (`isVisible`/`isEnabled`) to a GET response **under `meta.surface | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Surface.php |
 | [TableView row-filtering via apiWhereClause (options.where grammar, end to end)](features/tableview-apiwhereclause-row-filtering.md) | `TableViews.apiWhereClause` (TEXT, nullable) is the sanctioned, code-free way to restrict or exclude rows from a 2.0 table view. | api2/Component/Api/V2/V2.php, _underscore/Model/Client/TableView.php, toga2-supply/src/api/toga.ts |
 | [Tickets API (/v2/tickets)](features/tickets-api.md) | The generic ticket endpoint of the 2.0 REST API. | Component/Api/V2/V2.php |
+| [V2 API error/message codes (EV/EZ troubleshooting map)](features/v2-api-error-codes.md) | The V2 JSON engine (`Component/Api/V2/V2.php`) returns short **message codes** in the response `error` field, grouped by family: `EN-*` authentication, `EZ-*` a | api2/Component/Api/V2/V2.php |
 | [AWS CodePipeline Deployment via CodeConnections (GitHub → Elastic Beanstalk)](workflows/codepipeline-codeconnections-deploy.md) | 2.0 apps (`api2`, `_underscore`) are deployed through **AWS CodePipeline**. |  |
 | [New Environment Configuration & Provisioning (api2)](workflows/environment-configuration-and-provisioning.md) | What it takes for a 2.0 API environment (e.g. | api2/Config/<environment>.ini, api2/Controller/Index.php, dbchanges2/Core/2026-06-16a - DatabaseHosts for new QA QC stage demo environments.sql, _underscore/Route.php |

package/knowledge/2.0/apps/api2/features/v2-api-error-codes.md

@@ -0,0 +1,66 @@
+---
+title: "V2 API error/message codes (EV/EZ troubleshooting map)"
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-07-17
+owners: [mhammontree]
+files:
+  - api2/Component/Api/V2/V2.php
+related:
+  - ../../_underscore/features/acl-permission-chain.md
+  - scripted-api-post-body-args.md
+  - ../architecture.md
+---
+
+## Summary
+
+The V2 JSON engine (`Component/Api/V2/V2.php`) returns short **message codes** in the
+response `error` field, grouped by family: `EN-*` authentication, `EZ-*` authorization,
+`EV-*` validation, `EO-*` operation, plus `W*`/`D*`. This doc is the **troubleshooting map**
+for the codes you hit when adding a field or a scripted API to a V2 record — each with its
+root cause and the exact fix — so a teammate can go straight from the code to the missing
+migration instead of re-deriving it. All field/script ACL rows live in the **CLIENT** DB
+(`Records.aclDatabase = 'CLIENT'`), keyed by the caller's `roleId`.
+
+## The codes (cause → fix)
+
+| Code | Meaning | Root cause | Fix |
+|------|---------|------------|-----|
+| **EV-6** | Resource / route not found | A **scripted-API** route segment is being treated as a record uuid because no Record Script matches — i.e. the `Core.RecordScripts` route row is missing | Register the `Core.RecordScripts` row (`recordId`, `method`, `route`, `phpMethod`) |
+| **EV-8** | Request field does not exist | A field sent in the payload isn't registered as a **`Core.RecordFields`** row for that record | Register the field in `Core.RecordFields` (see the "add a field to a V2 record" recipe in the ACL doc) |
+| **EV-9** | No permission to write field | The field exists but the caller's role has no **`AclFieldPermissions`** grant (`isWritable=1`) in the CLIENT DB | Add the `AclFieldPermissions` row for the role (clone a writable sibling field's grant) |
+| **EZ-1** | Unauthorized record/script dispatch | Missing **`AclRecordScripts`** (scripted APIs) or the **`AclRecordPermissions`** four-table chain (records) for the caller's role | Grant `AclRecordScripts` (scripts) or complete the record-CRUD chain |
+| **EV-5** | Duplicate `transactionId` | The globally-unique `transactionId` was reused | Send a fresh unique `transactionId` per request |
+| **EV-12** | Record's parent not synced | (Fulfill & Ship) POST `/item-fulfillments` when the Sales Order isn't synced into Toga yet | `GET /sales-orders/syncNetsuiteSalesOrder?netsuiteInternalSalesOrderId=<id>` first |
+
+## How to diagnose
+
+1. **Resolve the role.** Field/script ACLs are keyed by `roleId` **in the CLIENT DB**, and role
+   ids differ per client — resolve by subselect (`SELECT id FROM Roles WHERE name='Base'`), never
+   hardcode. To find the right grant shape, inspect a **working sibling** field/script's rows.
+2. **EV-8 vs EV-9** are the two halves of adding a writable field: EV-8 = the Core `RecordFields`
+   registration is missing; EV-9 = the field exists but the Client `AclFieldPermissions` grant is
+   missing. You will typically hit EV-8 first, fix it, then hit EV-9.
+3. **EV-6 vs EZ-1** are the two halves of exposing a scripted API: EV-6 = no `Core.RecordScripts`
+   route (the segment falls through to record lookup); EZ-1 = the route exists but there's no
+   `AclRecordScripts` dispatch grant for the caller's role.
+
+## Related recipes
+
+- **Add a writable field to a V2 record (3-file migration)** and **expose a scripted API**
+  (RecordScript + AclRecordScripts): see
+  [ACL Permission Chain](../../_underscore/features/acl-permission-chain.md).
+- The response-envelope shape and code families: see [api2 architecture](../architecture.md).
+
+## Change history
+
+- 2026-07-17 — TRUE-79191: documented the EV-6/EV-8/EV-9/EZ-1 troubleshooting map (plus EV-5/EV-12)
+  discovered wiring the Signature Type field and the `addresses/validate` scripted route on Fulfill
+  & Ship — each code mapped to the missing migration (RecordField / AclFieldPermissions /
+  RecordScripts / AclRecordScripts) and the resolve-role-by-sibling technique. (mhammontree)
+</content>
+</invoke>

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/view/components/SelectedShipmentItemsTable.tsx, toga2-supply/src/pages/EditShipment/view/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/DUMMYUPDATESHIPMENTFIELDS.json, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/tailwind.config.cjs, toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx, toga2-supply/src/styles/index.scss, toga2-supply/src/components/ui/BaseInput/BaseInput.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/formatShipmentData.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 |
+| [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/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/DUMMYUPDATESHIPMENTFIELDS.json, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/renderEditShipmentFormInput.tsx, toga2-supply/tailwind.config.cjs, toga2-supply/src/pages/EditShipment/view/modals/ReturnShippingModal.tsx, toga2-supply/src/styles/index.scss, toga2-supply/src/components/ui/BaseInput/BaseInput.tsx, toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts, toga2-supply/src/pages/EditShipment/viewModel/signatureTypes.ts, toga2-supply/src/pages/EditShipment/view/modals/SelectReturnAddressModal.tsx, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/formatShipmentData.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

@@ -21,6 +21,8 @@ files:
   - toga2-supply/src/styles/index.scss
   - toga2-supply/src/components/ui/BaseInput/BaseInput.tsx
   - toga2-supply/src/pages/EditShipment/api/UpdateShipmentApi.ts
+  - toga2-supply/src/pages/EditShipment/viewModel/signatureTypes.ts
+  - toga2-supply/src/pages/EditShipment/view/modals/SelectReturnAddressModal.tsx
   - toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/formatShipmentData.ts
   - toga2-supply/src/pages/EditShipment/types.ts
   - toga2-supply/src/pages/Shipments/view/ShipmentsPage.tsx
@@ -209,6 +211,42 @@ bare string** — see the gotcha below before wiring a new select field.
 12px check glyph. This is the **shared** checkbox, so the change applies **app-wide**, not just to
 the shipment forms — audit other consumers when touching it.
 
+## Signature Type — 4-level enum (2026-07)
+
+Signature moved from a **boolean `requiresSignature`** to a **4-level `signatureType` enum**:
+**None Specified / Indirect / Direct / Adult** (cards read "No / Indirect / Direct / Adult Signature
+Required"). It persists on `TrackingNumbers.signatureType` and is now applied to the outbound label
+(see the carrier-shipping-labels doc's signature-type mapping + the UPS "no Indirect tier" rule).
+
+- **Single source of truth:** `src/pages/EditShipment/viewModel/signatureTypes.ts` holds the dropdown
+  options, the card-label helper `signatureCardLabel`, the legacy-boolean derivation
+  `requiresSignatureFromLevel`, and `SIGNATURE_CARRIER_MAP`. Change signature behavior here, not in
+  the components.
+- **Back-compat:** create + edit save paths send `trackingNumber.signatureType` **and still derive
+  `requiresSignature`** (via `requiresSignatureFromLevel`) so older consumers keep working. The API
+  read field lists request `signatureType`; edit rehydrates from it; shipment cards render a computed
+  `signatureLabel` with a legacy fallback for rows saved before the enum.
+- Backend: `TrackingNumbers.signatureType` column + `_Model_Client_TrackingNumber::$signatureType`
+  (registered via the 3-file V2-field migration — see the ACL doc).
+- **The whole-object react-select rule still applies** — `signatureType`'s form value is the option
+  OBJECT `{uuid,name}`; map on `.uuid`, rehydrate the object (see the react-select gotcha below).
+
+## Return Address validation modal — "Select Return Address" (2026-07)
+
+Saving a return address now runs a **carrier validation step** (Figma node 3037-17080). On Save the
+`ReturnShippingModal` calls `validateReturnAddress()` and **always** opens `SelectReturnAddressModal`,
+which shows the carrier-normalized **Suggested Address** vs the **Original** as radios (the Suggested
+heading always shows, with an empty state when the carriers return none), Cancel / Save; the chosen
+address is applied.
+
+- **Backend:** `validateReturnAddress()` (`UpdateShipmentApi.ts`) does `GET /addresses/validate`
+  (result at `response.data.addresses.validate`) — the migration-registered scripted route on the
+  existing USPS→FedEx→UPS `validateAddress` cascade (see the `_underscore` address-validation doc).
+- **⚠ State-code gotcha:** the stored state form value is only `{uuid, name}`, but USPS needs the
+  **2-letter code**. `getStates` already fetches `code`, but the `EditShipmentPage` mapping was
+  **dropping** it — carry `code` through the state options and resolve it at validation time, or
+  validation fails on a missing/blank state.
+
 ## Planned direction — "Fulfill & Ship" from an existing Item Fulfillment (future, Eric)
 
 A **third entry mode** is planned (distinct from Select-Items-create and the pencil-edit): a
@@ -459,6 +497,19 @@ not the base `_Model_Client_ItemFulfillment`. Tested with GroWrk; UPS support wa
 for Compass and is not yet in prod.
 
 ## Change history
+- 2026-07-17 — TRUE-79191: replaced the boolean `requiresSignature` with a **4-level `signatureType`
+  enum** (None Specified / Indirect / Direct / Adult) — `viewModel/signatureTypes.ts` is the single
+  source of truth (options, `signatureCardLabel`, `requiresSignatureFromLevel` back-compat,
+  `SIGNATURE_CARRIER_MAP`); save paths send `signatureType` and still derive `requiresSignature`; the
+  level is now applied to the outbound label (carrier mapping in the carrier-shipping-labels doc).
+  Added the **"Select Return Address" validation modal** (`SelectReturnAddressModal.tsx`;
+  `validateReturnAddress()` GET `/addresses/validate` → `data.addresses.validate`; Save always
+  validates then shows Suggested-vs-Original) and documented the **state-code gotcha** (carry `code`
+  through state options; USPS needs the 2-letter code the `{uuid,name}` value drops). Also: app-wide
+  `BaseInput` select-focus now uses `border-1` + inset ring (was `border-2`, which shifted text on
+  focus) and `BasicTable` gained `stickyHeader`/`headerCellPadding`/`tableContainerMarginBottom` props;
+  the rest of the layout/overflow pass (AuthLayout gap rebalance, page top-gap removals, device-list
+  grow-to-cap, shipment-card `w-full`/`min-h-full`) was cosmetic. (mhammontree)
 - 2026-07-15 — TRUE-79191: made the Edit Return Label **Addressee a searchable combobox** (native
   `<input list>` + `<datalist>`, filters + allows custom text, prefills via `applyWarehouse`); added a
   **backdrop-click discard guard** (guarded `BaseModal onClose` on `formState.isDirty`); restyled the

package/knowledge/INDEX.md

@@ -19,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **_underscore** (_Underscore) _(framework core)_ — 33 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 30 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 11 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 12 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)

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

@@ -2,7 +2,7 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
-| [Compass Approval-Decision Flow (Notifications & Manager Reassignment)](features/approval-decision-flow.md) | 2.0 | Compass's sales-order approval flow — approval/notification email lists, **manager reassignment**, VIP auto-approve, and EN/FR localization — lives **entirely i | _underscore/Model/Compass/ApprovalDecision.php, _underscore/Model/Compass/Usa/ApprovalDecision.php, _underscore/Model/Compass/Canada/ApprovalDecision.php |
+| [Compass Approval-Decision Flow (Notifications & Manager Reassignment)](features/approval-decision-flow.md) | 2.0 | Compass's sales-order approval flow — approval/notification email lists, **manager reassignment**, VIP auto-approve, and EN/FR localization — lives **entirely i | _underscore/Model/Compass/ApprovalDecision.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/Usa/ApprovalDecision.php, _underscore/Model/Compass/Canada/ApprovalDecision.php |
 | [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, _underscore/Model/Compass/PurchaseOrder.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client_Compass/2026-06-11 - AsnItemTrackingNumberAcl.sql, dbchanges2/Client_Compass/2026-06-15b - BackfillSA132781ItemFulfillmentTracking.sql, dbchanges2/Client_Compass/2026-06-16 - CleanupSA132763CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16b - CleanupSA132743CrossLineTracking.sql, dbchanges2/Client_Compass/2026-06-16c - BackfillSA132763C40QYUCTracking.sql, dbchanges2/Client_Compass/2026-06-18a - CleanupSA132898DuplicateTracking.sql, dbchanges2/Client_Compass/2026-06-18b - CleanupSA132881DuplicateTracking.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql |
 | [Cost Centers — Unit Locations, numeric-only policy](features/cost-centers.md) | 2.0 | A Compass "cost center" — the value a user picks in commerce and that lands on an order — is **not** a `CostCenters` row. | toga2-commerce/src/pages/Cart/api/CartApi.ts, worker1.5/crons/toga2/compass/import_locations.php, _underscore/Model/Compass/SalesOrder.php, api2/Component/Api/V2/V2.php, dbchanges2/Client_Compass/2026-07-06 - RemoveNonNumericCostCenters.sql |
 | [Compass: Item-Fulfillment TableViews (for-sales-order-items & for-sales-orders, tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | Two sibling Compass TableViews in `Client_Compass` display fulfilled items in toga2-supply, both driven by `TableViews` / `TableViewJoins` / `TableViewFields` c | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql, dbchanges2/Client_Compass/2026-06-11 - ItemFulfillmentsForSalesOrdersTableView.sql, dbchanges2/Client_Compass/2026-06-15a - FixItemFulfillmentTrackingNumberJoins.sql, dbchanges2/Client/2026-07-15a - ExcludeFeeItemsFromItemFulfillmentsForSalesOrdersView.sql |

package/knowledge/clients/compass-usa/features/approval-decision-flow.md

@@ -6,10 +6,11 @@ project: _Underscore
 client: compass-usa
 type: client-feature
 status: active
-updated: 2026-07-16
-owners: ["apeterson"]
+updated: 2026-07-17
+owners: ["apeterson", "dfranks"]
 files:
   - _underscore/Model/Compass/ApprovalDecision.php
+  - _underscore/Model/Compass/SalesOrder.php
   - _underscore/Model/Compass/Usa/ApprovalDecision.php
   - _underscore/Model/Compass/Canada/ApprovalDecision.php
 related:
@@ -54,6 +55,24 @@ Because the divergence is a runtime branch and not an override, do **not** add p
 the empty subclasses — extend the shared parent and branch there if a genuine tenant difference is
 needed.
 
+### VIP manager auto-approve — the rule and its three (all supervisor-derived) triggers
+A single rule governs VIP auto-approve: a **manager-stage (step 2)** approval auto-approves iff the
+assigned manager's `Users.c_isVip = 1` **AND** the order subtotal
+`<= _Model_Compass_SalesOrder::AUTO_APPROVE_IF_MANAGER_IS_VIP_AND_UNDER_AMOUNT` (= `5000`).
+Subtotal = `SUM(SalesOrderItems.quantity * price)` via `_Model_Client_SalesOrder::_subtotal()`.
+
+That rule is evaluated in exactly three places, and **all three derive the manager from a
+supervisor relationship**:
+- **(a) Order creation** — `_Model_Compass_SalesOrder::postPost`, inside
+  `elseif (!empty($managerUserUuid))`, where `$managerUserUuid` comes from the requester's
+  `Users.supervisorUserId`.
+- **(b) "Order for" / contact change** — `_Model_Compass_SalesOrder::postPut`, only when the PUT
+  payload changes `contact`; it re-derives the manager from the *new* contact's supervisor.
+- **(c) Manager reassignment** — `_Model_Compass_ApprovalDecision::handleManagerReassignment`, wired
+  into `postPut` **only** (added by TRUE-78851). It writes log notes
+  `"Manager reassigned — approval decision reset"` (non-VIP) or
+  `"Manager approval skipped due to VIP logic"` (VIP auto-approve).
+
 ### Manager reassignment and the notification list
 When a step-2 (Manager) approval decision is **reassigned** to a new manager,
 `_swapManagerEmailAddress()` updates the order's CC/notification list in `SalesOrderEmailAddresses`:
@@ -67,6 +86,22 @@ requester**. All of these comparisons are case-insensitive (`strcasecmp()`), mat
 `getFilteredCcEmails()`.
 
 ## Gotchas / known issues
+- **VIP auto-approve is bypassed when the requester has no supervisor (POST-path gap).** All three
+  VIP evaluation triggers above are supervisor-derived. When a requester has
+  `Users.supervisorUserId = NULL`, order creation skips the manager branch entirely (no step-2
+  decision, no manager). If an admin then *manually adds* a manager, that **CREATES** the step-2
+  decision as a POST to `/approval-decisions` → `_Model_Compass_ApprovalDecision::postPost`, which
+  calls only `logApprovalDecision` + `handleApprovalDecision` — **neither contains VIP auto-approve
+  logic**. So a VIP manager under the $5000 threshold added to a no-supervisor order **never
+  auto-approves** and must be manually overridden. TRUE-78851 only wired `handleManagerReassignment`
+  into `postPut` (reassigning an existing manager decision), never the first assignment (POST).
+  - **Diagnostic signature:** absence of **both** `handleManagerReassignment` log notes in
+    `Logs_<Tenant>.Record`, combined with a step-2 decision whose `approvalDecisionTypeId = NULL`
+    and `decidedByUserId` = the admin (not the manager). The order event log lives in the logs
+    cluster schema `Logs_Compass` (per-client `Logs_<Tenant>`), table `Record`, columns
+    `(recordId, primaryKeyId, userId, timestamp, note)`; SalesOrder `RECORD_ID = 14`.
+  - Real incident: order SA134461 — VIP manager Spyros Gravas, subtotal $926.47 (both auto-approve
+    conditions met) still required manual override because the requester had no supervisor.
 - **Never drop the order requester from notifications on manager reassignment.** If the outgoing
   manager happens to also be the order requester (same email), deleting the old-manager address
   from `SalesOrderEmailAddresses` would silently remove the requester from all order notifications.
@@ -81,6 +116,13 @@ requester**. All of these comparisons are case-insensitive (`strcasecmp()`), mat
   intentionally empty; the tenant branch lives in the parent on `clientIdentifier`.
 
 ## Change history
+- 2026-07-17 — Documented the VIP manager auto-approve rule (VIP manager + subtotal ≤ $5000) and
+  its three supervisor-derived triggers (`postPost` creation, `postPut` contact change,
+  `handleManagerReassignment` on `postPut`), plus the **POST-path gap**: a requester with no
+  supervisor never gets VIP auto-approve because a manually-added manager creates the step-2 decision
+  via `_Model_Compass_ApprovalDecision::postPost`, which has no VIP logic (TRUE-78851 covered only
+  the `postPut` reassignment path). Recorded the diagnostic signature and prod incident SA134461.
+  Investigation/planning only — no code shipped. (dfranks)
 - 2026-07-16 — Fixed `_swapManagerEmailAddress()` dropping the order requester from the order's
   notification list (`SalesOrderEmailAddresses`) when a step-2 manager was reassigned and the
   outgoing manager's email also belonged to the requester: now looks up the requester email via

package/package.json

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