toga-ai 1.0.445 → 1.0.447

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

@@ -4,7 +4,7 @@
 |-----|---------|-------|
 | [Proposed — git-sourced base+overlay JSON authoring for the Surface layer](architecture/surface-authoring-proposal.md) | A **proposal / handoff recommendation** (not implemented) that the Surface layer's *authoring* model move off hand-authored SQL against the `SurfaceOverrides` E | _underscore/Model/Core/Surface.php, _underscore/Model/Client/SurfaceOverride.php |
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
-| [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, _underscore/Model/Client/TrackingNumber.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission.sql |
+| [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, _underscore/Model/Client/TrackingNumber.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission.sql, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql |
 | [Address Validation (carrier waterfall + validateAddress scripted endpoint)](features/address-validation.md) | `_Model_Client_Address::validateAddress` verifies a US address against a **carrier waterfall (USPS → FedEx → UPS)** and returns a single canonical, carrier-norm | _underscore/Model/Client/Address.php |
 | [_ApiRequest ENCODE__JSON now sends Content-Type: application/json](features/apirequest-json-content-type.md) | `_ApiRequest::execute()`'s `ENCODE__JSON` branch json-encoded the request body but never set a `Content-Type` header. | _underscore/ApiRequest.php |
 | [Assortment Name Translation (AssortmentTranslations sidecar)](features/assortment-name-translation.md) | Serves Assortment (product-grouping) **names** in multiple languages by adding a per-language **sidecar** table `AssortmentTranslations`, reusing the platform's | _underscore/Model/Client/AssortmentTranslation.php, dbchanges2/Client/2026-06-26a - AssortmentTranslations.sql, dbchanges2/Core/2026-06-26a - AssortmentTranslationsRecord.sql, dbchanges2/Client/2026-06-26b - AssortmentTranslationsAcl.sql |
@@ -30,4 +30,4 @@
 | [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 |
+| [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/Controller/Index.php, api2/index.php, api2/.htaccess |

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-23
+updated: 2026-07-27
 owners: ["jcardinal", "mhammontree", "tcox"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -15,6 +15,7 @@ files:
   - dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql
   - dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql
   - dbchanges2/Client/2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission.sql
+  - dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql
 ---
 
 ## Summary
@@ -53,6 +54,16 @@ writable). Without it the field is rejected on write **and** is unreadable:
   fully registered (`Core.RecordFields` row present, so no `EV-8`) yet still `EZ-2` because it has
   no `AclFieldPermissions` row — **registering a field and granting access to it are two separate
   steps**, and shipping the field registration without the grant is a recurring launch blocker.
+- **⚠ The V2 GET response's OUTPUT field list is itself BUILT from `AclFieldPermissions`, so a field
+  with no grant is often SILENTLY OMITTED from the response body — not surfaced as an `EZ-2` error.**
+  `_Component_Api_V2::getAclFieldPermissions()` (`api2/Component/Api/V2/V2.php` ~L5795) resolves the
+  caller's readable/writable set, and the output serializers (`foreach ($aclFieldPermissions as $field
+  => $isWritable)` output loops, ~L3181 / L6082 / L6302) iterate **only** that set — a `RecordField`
+  with no grant row for the caller's role never enters the list, so it just isn't in the JSON (200,
+  no `messages[]`). This is **beyond the known EV-9 (write) rule: `AclFieldPermissions` gates READ
+  VISIBILITY too.** Concrete symptom (TRUE-79191): `Measures.measureType` was registered but ungranted,
+  so it came back absent and the frontend unit dropdowns were empty. When a field renders blank with no
+  error, check for a missing `AclFieldPermissions` grant before suspecting the selector or the data.
 - **`AclFieldPermissions` is `UNIQUE (recordFieldId, roleId)`** (Client blank DDL) — guard inserts
   with `NOT EXISTS`. For a **read-only, server-written** field (one populated by a `postPost`
   interceptor rather than the API caller), grant `isWritable = 0`.
@@ -168,6 +179,16 @@ rejects the write with a **specific code** (see the
    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.
+   **⚠ When the grant FANS OUT across ALL client DBs, mirror a STABLE, universally-present sibling —
+   not a recently-added one.** A migration that copies a sibling's grants only works on a client where
+   that sibling *itself* has grants. Mirror a long-established field (e.g. the FK `shippingMethodId`)
+   whose `AclFieldPermissions` rows exist in **every** client DB. Mirroring a newly-added field
+   **fails silently** on clients where that field's own grants haven't propagated: TRUE-79191's
+   measure-id grant first mirrored `needsReturnLabel` and ended up ungranted on `Client_True`
+   (verified: `Client_True` had `shippingMethodId` grants but **no** `needsReturnLabel` grant) → the
+   new field was EV-9 on write / omitted on read there. Because the clone reads each client's **own**
+   sibling rows, it also correctly adapts to that client's role set (Growrk role 1; Compass roles
+   1,3,4) — another reason to resolve by subselect, never hardcode.
 4. **Generated model-class declaration** (`_underscore/Model/Client/<Name>.php`) — the field must
    be declared on the **generated** PHP model class, e.g.
    `public $needsReturnLabel = self::FIELD_BOOLEAN;`. **Without it the API returns `EO-1`**
@@ -206,6 +227,16 @@ the field.
 
 ## Change history
 
+- **2026-07-22** — TRUE-79191: documented that the V2 GET **OUTPUT** field list is itself built from
+  `AclFieldPermissions` (`getAclFieldPermissions` + the output `foreach` loops in
+  `api2/.../V2.php`), so an **ungranted field is SILENTLY OMITTED** from the response (200, no
+  `messages[]`) — read visibility is gated, not only writes (beyond the EV-9 write rule). Symptom:
+  `Measures.measureType` absent → empty unit dropdowns. Also added the **cross-client fan-out rule**:
+  a grant migration that clones a sibling must mirror a **stable, universally-present** sibling
+  (e.g. `shippingMethodId`), not a recently-added one — mirroring `needsReturnLabel` left the new
+  measure-id field ungranted on `Client_True` (which had `shippingMethodId` grants but no
+  `needsReturnLabel` grant); cloning each client's own rows also adapts to its role set
+  (Growrk role 1; Compass 1,3,4). (mhammontree)
 - **2026-07-23** — TRUE-79533: noted that a **read-only field only needs a grant on the role(s) that
   actually read it** — mirror a sibling field of the same kind the readers already consume rather than
   granting every role. The standard FK `serviceAddressId` mirrored `saleItemId`'s reader, **role 1** in

package/knowledge/2.0/apps/_underscore/workflows/local-db-refresh-from-beta.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: workflow
 status: active
-updated: 2026-07-09
-owners: ["apeterson"]
+updated: 2026-07-27
+owners: ["apeterson", "mhammontree"]
 files:
   - api2/Config/
   - _underscore/Loader.php
@@ -87,6 +87,14 @@ Order matters — dump first so a failed dump never wipes a local schema it can'
   `Client_CompassCanada` selected as the active DB in your client — a standalone `USE` line run
   as a separate statement does **not** carry over, and the tables land in the wrong schema. See
   [tracking-number-bridges](../features/tracking-number-bridges.md) for the bridge tables.
+- **⚠ Pulling updated models from prod WITHOUT applying the matching `dbchanges2` migrations locally
+  → `1054 Unknown column`.** The mirror image of the missing-model 500 above: if you `git pull`
+  `_underscore` models that reference a column a **newer migration** adds, but your local client DB
+  hasn't run that migration, queries fail with `1054 Unknown column`. Concrete case:
+  `Items.isFulfillable` (added by the 2026-07-17 migration) — the pulled Item model selected the
+  column before the local schema had it. **Fix:** apply the pending `dbchanges2` migrations in date
+  order, or reset the local client DB(s) from a beta snapshot (the steps above). Keep local
+  `_underscore` **and** the local schema on the same migration point.
 - **The logs-DB write trap still applies.** A reset only refreshes the schemas you loop over; if
   you skip `Logs_<Id>` the first request 500s (`Unknown database 'logs_<id>'`) on the logging
   write. See [per-client DB connections](../features/per-client-database-connections.md).
@@ -97,6 +105,10 @@ Order matters — dump first so a failed dump never wipes a local schema it can'
 
 ## Change history
 
+- 2026-07-27 — TRUE-79191: added the reverse-drift gotcha — pulling updated `_underscore` models from
+  prod **without** applying the matching `dbchanges2` migrations locally throws `1054 Unknown column`
+  (e.g. `Items.isFulfillable` from the 2026-07-17 migration); apply pending migrations or reset the
+  local client DB from a beta snapshot. (mhammontree)
 - 2026-07-09 — Initial capture: non-locking `mysqldump` recipe (beta `admin` lacks `RELOAD`), the
   VPN-only beta host, and the two recurring post-reset side-effects — a missing `_Model_Client_*`
   autoload 500 (pull the model file, no cache) and the CompassCanada 17-table drift

package/knowledge/2.0/apps/_underscore/workflows/running-a-2.0-app-locally.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: workflow
 status: active
-updated: 2026-07-09
+updated: 2026-07-27
 owners: ["mhammontree"]
 files:
   - _underscore/Environment.php
@@ -14,6 +14,7 @@ files:
   - _underscore/Database.php
   - _underscore/Route.php
   - api2/Component/Api/V2/V2.php
+  - api2/Controller/Index.php
   - api2/index.php
   - api2/.htaccess
 related:
@@ -95,6 +96,15 @@ Checked in `V2.php` (~lines 485–800):
 
 ## Gotchas / known issues
 
+- **⚠ On a locked-down Windows dev box, PCRE JIT crashes EVERY api2 route with a 500.** During api2
+  bootstrap (`Controller/Index.php`), `Sentry\init()` runs a `preg_split()` that fails with
+  **`preg_split(): Allocation of JIT memory failed, PCRE JIT will be disabled`** — on a hardened
+  Windows Enterprise machine the OS refuses the executable-memory (W^X) allocation the PCRE JIT needs.
+  The `_underscore` error handler **escalates that warning to a fatal**, so **every V2 route returns
+  500**, masquerading as a code bug. **Fix (local only): set `pcre.jit=0` in `php.ini` and restart
+  Apache.** Nothing to ship — beta/prod PHP is permitted to allocate executable memory, so the JIT
+  works there and there is no code change.
+
 - **The silent `Route.php:525` error** — `"Failed to determine how to render view for route
   '/v2/...'"` (thrown at `_underscore/Route.php:525`) means the API handler returned **no**
   response, so `_Route` fell through to view rendering. It is thrown during bootstrap
@@ -118,6 +128,10 @@ Checked in `V2.php` (~lines 485–800):
 
 ## Change history
 
+- 2026-07-27 — TRUE-79191: added the **PCRE JIT** gotcha — on a locked-down Windows Enterprise dev
+  box `Sentry\init()` (`api2/Controller/Index.php`) hits `preg_split(): Allocation of JIT memory
+  failed`, which the `_underscore` error handler escalates to a fatal, 500ing **every** V2 route;
+  fix is `pcre.jit=0` in `php.ini` + Apache restart (local only — nothing to ship). (mhammontree)
 - 2026-07-09 — Documented the full local browser-run dependency chain (Apache `ENVIRONMENT`,
   `dev-*`→`dev` slug collapse, Core-driven client-DB registration, `/v2/auth/login` browser gate,
   the `Route.php:525` silent-fallthrough gotcha, and the stale-Core "missing model file" fatal),

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/components/ui/Tables/BasicTable/BasicTable.tsx, toga2-supply/src/components/ui/Tables/types.ts, toga2-supply/src/components/ui/GoogleMapsLink.tsx, toga2-supply/src/pages/ShipmentItems/view/forms/ShipmentItemsTable.tsx, toga2-supply/src/pages/ShipmentItems/api/ShipmentItemsApi.ts, toga2-supply/src/pages/ShipmentItems/types.ts, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/RETURNLABELFIELDS.json, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/components/ui/BaseInput/UnitSelect.tsx, toga2-supply/src/pages/EditShipment/view/modals/SerialNumbersModal.tsx, 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 |
+| [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 | _underscore/Model/Client/Measure.php, _underscore/Model/Client/TrackingNumber.php, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/getEditShipmentFormOptions.ts, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/validateFormOnSubmit.ts, toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/checkDimensions.ts, toga2-supply/src/components/ui/Tables/BasicTable/BasicTable.tsx, toga2-supply/src/components/ui/Tables/types.ts, toga2-supply/src/components/ui/GoogleMapsLink.tsx, toga2-supply/src/pages/ShipmentItems/view/forms/ShipmentItemsTable.tsx, toga2-supply/src/pages/ShipmentItems/api/ShipmentItemsApi.ts, toga2-supply/src/pages/ShipmentItems/types.ts, toga2-supply/src/pages/EditShipment/viewModel/FIELDS/RETURNLABELFIELDS.json, toga2-supply/src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx, toga2-supply/src/components/ui/BaseInput/UnitSelect.tsx, toga2-supply/src/pages/EditShipment/view/modals/SerialNumbersModal.tsx, 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

@@ -6,9 +6,14 @@ project: TOGa Supply
 client: shared
 type: feature
 status: active
-updated: 2026-07-21
+updated: 2026-07-27
 owners: [mhammontree]
 files:
+  - _underscore/Model/Client/Measure.php
+  - _underscore/Model/Client/TrackingNumber.php
+  - toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/getEditShipmentFormOptions.ts
+  - toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/validateFormOnSubmit.ts
+  - toga2-supply/src/pages/EditShipment/helpers/ShipmentDetailsForm/checkDimensions.ts
   - toga2-supply/src/components/ui/Tables/BasicTable/BasicTable.tsx
   - toga2-supply/src/components/ui/Tables/types.ts
   - toga2-supply/src/components/ui/GoogleMapsLink.tsx
@@ -302,26 +307,41 @@ existing IF), `fulfillShipment` + `generateReturnLabel` (label), `saveShipmentTo
 (push-back). New pieces needed: the punch-out entry carrying an IF id, and a **label-only mode**
 (skip the create step). This is a separate feature/ticket — recorded as planned direction, not done.
 
-## Planned direction — persist package dimension + volume Units of Measure (design, 2026-07-21)
-
-**Design decision recorded for future work (not implemented this session).** Today the package
-dimension in./cm selector is **visual-only** and `TrackingNumbers` stores `length`/`width`/`height`
-with **no unit**. The plan is to persist the package **DIMENSION** unit (for L/W/H) and the **VOLUME**
-unit on the tracking record.
-
-- **Recommended design = ZERO new tables, only columns.** REUSE the existing client **`Measures`**
-  table + **`_Model_Client_Measure`** model (already referenced by `Items.defaultMeasureId`): add a
-  **`measureType` ENUM** (LENGTH / VOLUME / WEIGHT / COUNT — per Jeff the types are enumerators, so
-  **no separate `MeasureTypes` table**) plus a **`conversionFactorToBase`** column, and add
-  **`dimensionMeasureId` / `volumeMeasureId`** FK columns on **`TrackingNumbers`**.
-- **Carrier constraint drives the conversion factor.** FedEx/UPS ship APIs accept only **IN/CM**
-  dimension units and **LB/KG** weight units, so the chosen measure must map/convert to the carrier
-  enum — hence `conversionFactorToBase`. **Volume is NOT sent to carriers** (dimensional weight is
-  derived from L/W/H).
-- **Alternative (documented for opt-in):** two dedicated new tables instead of reusing `Measures`.
-- Spans `_underscore` (Measure/TrackingNumber models), `dbchanges2`, and `api2`; full plan + the
-  deployment order live in external working files (`package_units_of_measure_plan.md`,
-  `TRUE-79191_deployment_order.md`) — not mirrored into the KB.
+## Package Units of Measure (weight + dimensions) — IMPLEMENTED (TRUE-79191, 2026-07-22)
+
+The package **weight** and **dimensions** on the Update Info / Edit Shipment form now have **real
+unit selectors** (base **Pound** / **Inch**), replacing the earlier visual-only placeholder. The
+chosen units **persist on the tracking number** and **rehydrate on reopen**. Verified end-to-end
+(the saved `TrackingNumber` carries the selected measure ids from the frontend create payload).
+Commit `e91f7029d`. **Supersedes the earlier design** (VOLUME and COUNT dropped entirely;
+`dimensionMeasureId` → `lengthMeasureId`; `weightMeasureId` added).
+
+- **Data model — ZERO new tables (design confirmed with product owner Jeff).** Reuse the existing
+  client **`Measures`** table (`id`/`uuid`/`slug`/`name`/`symbol`) and add two columns:
+  **`measureType ENUM('LENGTH','WEIGHT')`** and **`conversionFactorToBase DECIMAL(18,9)`**.
+- **Base units seeded into every client:** **Inch** (LENGTH, factor `1`) and **Pound** (WEIGHT,
+  factor `1`). **Convention: `value_in_base = value * conversionFactorToBase`.** Metric (cm/kg) is an
+  **opt-in per-client seed** added later; the base always stays Inch/Pound. Carrier constraint is the
+  reason a base/conversion exists at all — FedEx/UPS ship APIs accept only IN/CM + LB/KG.
+- **`TrackingNumbers` gains two FKs** (hard DB constraints → `Measures`): **`lengthMeasureId`** (one
+  unit governs length/width/height) and **`weightMeasureId`**. Existing rows are **backfilled to
+  Inch/Pound** (one-time migration; **not** re-run-safe).
+- **Models (`_underscore`):** `_Model_Client_Measure` gains `measureType` (`FIELD_CHAR`) +
+  `conversionFactorToBase` (`FIELD_DECIMAL`); `_Model_Client_TrackingNumber` gains
+  `lengthMeasureId`/`weightMeasureId` (`FIELD_FOREIGNKEY` → `_Model_Client_Measure`).
+- **api2 needs NO code.** The new fields ride the metadata-driven V2 engine — exposed purely via Core
+  `RecordFields` + Client `AclFieldPermissions`. **The `AclFieldPermissions` grant is mandatory for
+  READ, not only write** — see the acl-permission-chain doc's field-registration recipe and the
+  read-visibility rule (a registered field with no grant is silently omitted from the response, which
+  presented here as empty unit dropdowns).
+- **Frontend:** two react-hook-form selects fed by **`GET /v2/measures`**, split client-side by
+  `measureType`. **The FK is WRITTEN as a nested relation OBJECT `{uuid}`** (`lengthMeasure` /
+  `weightMeasure`), exactly like the sibling `shippingCarrier` — **NOT a scalar id**; read
+  field-selectors request `lengthMeasure`/`weightMeasure`. (Same whole-object react-select rule as
+  every other select in these forms — see that gotcha.)
+- **Migrations (`dbchanges2`):** `Core/2026-07-22a - MeasureUomRecordFields.sql`,
+  `Client/2026-07-22a - MeasureUomColumns.sql`, `Client/2026-07-22b - TrackingNumberMeasureIds.sql`,
+  `Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql`.
 
 ## Sources — meeting notes / decision origins
 
@@ -598,6 +618,24 @@ the call 403s and returns no label.
   programmatic `setValue` for a user-meaningful prefill must pass `{ shouldDirty: true }` or the form
   still reads "clean" (also affects the mint dirty-border above). File:
   `EditShipment/view/modals/ReturnShippingModal.tsx`.
+- **⚠ A submit handler must branch on a validation helper's RETURN value, NOT on the same-tick
+  `errors` snapshot after `setError`.** Same RHF-formState-lag family as the `isDirty` gotcha above:
+  the destructured `errors` object is one render **behind** `setError`/`clearErrors`, so a helper that
+  sets field errors and a caller that then reads `Object.keys(errors)` on the **same tick** see a
+  stale (empty) `errors` — the FIRST submit sailed past validation straight to the API even with
+  invalid fields. **Two rules for any toga2-supply form doing manual RHF validation on submit:**
+  (1) the helper must **RETURN a fresh boolean/result** and the caller must branch on that return
+  value, never on the same-tick `errors` snapshot; (2) the helper must **`clearErrors` on the
+  now-valid path**, not only `setError` on the invalid path. *Concrete failure:* `checkDimensions`
+  had branches for every partial L/W/H combination and for all-absent but **none for all-present**,
+  so once a partial submit flagged a dimension, completing all three never cleared it and submit
+  stayed blocked in RHF state **permanently**. Fix: `validateFormOnSubmit.ts` and `checkDimensions.ts`
+  now return a boolean (`hasErrors`) and clear errors on the valid state; `EditShipmentForm.tsx`
+  branches on the returned result. (This validation now also runs in **edit mode** — detail/address
+  fields were previously skipped on the edit save path.) Files:
+  `EditShipment/helpers/ShipmentDetailsForm/validateFormOnSubmit.ts`,
+  `EditShipment/helpers/ShipmentDetailsForm/checkDimensions.ts`,
+  `EditShipment/view/components/forms/EditShipmentForm.tsx`.
 - **⚠ api2 V2 field SELECTORS are dot-paths of REAL DB column names — a wrong name silently returns
   nothing.** V2 responses select fields by dot-path (e.g.
   `"itemFulfillmentItems.salesOrderItem.item.skuNumber"`). The real `Items` columns are **`skuNumber`
@@ -671,6 +709,17 @@ not the base `_Model_Client_ItemFulfillment`. Tested with GroWrk; UPS support wa
 for Compass and is not yet in prod.
 
 ## Change history
+- 2026-07-22 — TRUE-79191 (commit `e91f7029d`, full-stack): **IMPLEMENTED package Units of Measure** —
+  the package weight + dimensions now have real Pound/Inch unit selectors that persist on the
+  `TrackingNumber` and rehydrate on reopen (verified end-to-end). ZERO new tables: reused the client
+  `Measures` table + `_Model_Client_Measure` with `measureType ENUM('LENGTH','WEIGHT')` +
+  `conversionFactorToBase DECIMAL(18,9)` (base Inch/Pound factor 1, `value_in_base = value *
+  conversionFactorToBase`, metric opt-in later); `TrackingNumbers` gained `lengthMeasureId` (governs
+  L/W/H) + `weightMeasureId` FKs (existing rows backfilled Inch/Pound, one-time). **VOLUME + COUNT
+  dropped** and `dimensionMeasureId` → `lengthMeasureId` vs the earlier design. api2 needed NO code
+  (metadata-driven: Core `RecordFields` + Client `AclFieldPermissions`); the FK is written as a nested
+  relation object `{uuid}` like `shippingCarrier`. Migrations `Core/2026-07-22a`, `Client/2026-07-22a
+  /b/c`. (mhammontree)
 - 2026-07-21 — TRUE-79191 (commit `651e9d9d0`, toga2-supply UI fixes + UoM design): fixed the shared
   **`GoogleMapsLink`** mapping the recipient instead of the address (excluded `addressee`; read
   `street || line1` not `line1`; killed an always-true empty-part filter and a `replace`+`encodeURIComponent`
@@ -769,6 +818,13 @@ for Compass and is not yet in prod.
   the form via `getValueFromPath`'s unguarded `.split`). Remaining Figma tweaks (Dimensions in./cm
   dropdown + gaps, Item Count right-align, return-label row gaps, shipment-card indicator top gap) were
   cosmetic — no doc change. (mhammontree)
+- 2026-07-27 — TRUE-79191 (CodeRabbit review pass): fixed the Edit Shipment form's **first-submit
+  validation bypass** — `validateFormOnSubmit`/`checkDimensions` now RETURN a boolean and the submit
+  handler branches on that instead of the stale same-tick `errors` snapshot; `checkDimensions` now
+  clears errors on the all-present dimensions path (previously had no all-present branch, so a partial
+  submit could block submit permanently). Edit mode now runs the same detail/address validation
+  (previously skipped) and `updateShipment` returns step-identifying failures. Recorded as a reusable
+  RHF-validation gotcha. (mhammontree)
 - 2026-07-14 — TRUE-79191 (commit `724d17c1a`): fixed **Signature Type** not saving/rehydrating —
   documented the reusable **whole-object react-select** convention (`{uuid,name}`; map on `.uuid`,
   rehydrate the object) as a gotcha; the string comparison `data.signatureType === "Required"`

package/package.json

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