toga-ai 1.0.487 → 1.0.489

package/.claude/settings.json

@@ -41,6 +41,26 @@
             "timeout": 3000
           }
         ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \".claude/hooks/toga/dbchanges2-cluster-isolation.js\"",
+            "timeout": 3000
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \".claude/hooks/toga/dbchanges2-record-ids.js\"",
+            "timeout": 3000
+          }
+        ]
       }
     ],
     "PostToolUse": [

package/knowledge/2.0/apps/dbchanges2/architecture.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: architecture
 status: active
-updated: 2026-07-29
+updated: 2026-07-31
 owners: [jcardinal, mhammontree, bala, ajean]
 files:
   - Core/
@@ -43,6 +43,9 @@ UI config) — **not just schema**; a schema-only blank produces non-functional
 `Archive_*`, `Logs*`, and `Cache` are on **separate production clusters**, so any
 `OtherDatabase.Table` reference is unrunnable in production even though it works locally
 (see *Database isolation* below; enforced by the `dbchanges2-cluster-isolation` hook).
+**`Core.Records` and `Core.RecordFields` are the only two tables platform-wide with
+team-maintained `id`s** — ask the developer for the next value before inserting (never
+`AUTO_INCREMENT`), and hardcode those `id`s wherever they are referenced, foreign keys included.
 
 ## File naming convention (the execution contract)
 
@@ -189,6 +192,61 @@ literals are stripped first, and table **aliases** (`rf.id`, `sibling.roleId`) a
 > is **not** subject to it. If the hook ever misfires on legitimate SQL, `DBCHANGES2_ISOLATION_DISABLED=1`
 > is an escape hatch **for false positives only** — never to land a cross-database query.
 
+## `Core.Records` / `Core.RecordFields` — the only hardcoded `id`s on the platform
+
+These **two tables, and only these two**, have **team-maintained primary keys**. Their `id`
+values are treated as **stable, platform-wide constants**: the team tracks the next available
+value **in the developer chat**, and every environment carries the same `id` for the same record
+/ field. Nothing else on the platform may have a hardcoded `id`.
+
+This is what makes the *Database isolation* rule above practical — it is the reason a
+`Client_<Tenant>` migration never needs to read `Core` to find a `recordFieldId`.
+
+### Inserting into them — ASK FIRST, never rely on AUTO_INCREMENT
+
+**When a change inserts into `Core.Records` or `Core.RecordFields`, stop and ask the developer
+for the next `id` value(s)**, then write them as explicit literals:
+
+```sql
+# Core/2026-07-31a - Add entitlements serviceAddressId field.sql
+# id values 4187, 4188 assigned by the team (developer chat) — do NOT let AUTO_INCREMENT pick.
+INSERT INTO RecordFields (id, uuid, recordId, `field`)
+VALUES (4188, '<pre-generated v4 uuid>', 219, 'serviceAddressId');
+```
+
+**Never omit `id` and let MySQL's `AUTO_INCREMENT` assign it.** The column's `AUTO_INCREMENT`
+definition still exists, but it is **not the source of truth** — allowing it to assign a value
+lets environments drift apart, and every hardcoded reference to that `id` (in other databases,
+in PHP, in other migrations) then points at the wrong row or nothing at all. There is no way to
+detect this from inside the migration; it simply produces silently wrong ACL/field wiring.
+
+Because the `id`s must be reserved by a human, **this cannot be guessed or derived** — asking is
+mandatory, not a courtesy. Record the assigned values in a comment at the top of the file so the
+next reader knows they were allocated, not invented.
+
+### Referencing them — hardcode the `id`, including foreign keys
+
+Anywhere a query references one of these rows — **and anywhere a foreign key points at them**
+(`recordId`, `recordFieldId`, and their equivalents) — **hardcode the numeric `id`**. Do not look
+it up:
+
+```sql
+# Client_Compass/2026-07-31a - Grant serviceAddress field write.sql
+# recordFieldId 4188 = Core.RecordFields entitlements.serviceAddressId (team-assigned constant)
+INSERT INTO AclFieldPermissions (uuid, recordFieldId, roleId, isWritable)
+VALUES ('<pre-generated v4 uuid>', 4188, 3, 1);
+```
+
+This applies equally to SQL embedded in PHP in `worker2` / `api2` / `_underscore` — a hardcoded
+`recordFieldId` is correct and preferred there too.
+
+> **Always comment what the number is.** A bare `4188` is unreadable and unverifiable six months
+> later. Name the record/field it refers to, as above.
+
+Note that the `uuid` on these rows is **also** stable and environment-consistent, so
+`WHERE uuid = '<literal>'` is a valid alternative when a readable key is preferred — but the
+`id` is the team-maintained one, and it is what foreign keys store.
+
 ## `_modules` — reusable, opt-in change-sets
 
 Some change-sets aren't applied to every client — only to clients that use a given **module**
@@ -295,6 +353,12 @@ its own header.)
    foreign ids with a hardcoded v4 UUID literal or an in-database slug/natural key, or split the
    work into one file per database folder. See *Database isolation* above — enforced by the
    `dbchanges2-cluster-isolation` hook.
+9. **Inserting into `Core.Records` or `Core.RecordFields`? ASK the developer for the next `id`.**
+   These are the **only two tables on the platform with team-maintained primary keys** (tracked in
+   the developer chat). Write the assigned `id` as an explicit literal — **never** let
+   `AUTO_INCREMENT` assign it. Conversely, **always hardcode** these `id`s where they are
+   referenced, including in foreign keys (`recordId`, `recordFieldId`) from other databases. See
+   *`Core.Records` / `Core.RecordFields`* above.
 
 ## Bulk data loads — batch, and stage large sets in a temp table
 
@@ -447,7 +511,16 @@ defined in `2.0/apps/_underscore/architecture.md`, and its change files create/a
 tables that `_Model_*` classes map to.
 
 ## Change history
-- 2026-07-29 — **Added *Database isolation — never query across databases* (HARD RULE) + rule #8.**
+- 2026-07-31 — **Added *`Core.Records` / `Core.RecordFields` — the only hardcoded `id`s on the
+  platform* + rule #9.** These two tables are the **only** ones platform-wide whose `id` is a
+  team-maintained constant: the next available value is tracked **in the developer chat**, so a
+  migration inserting into them must **ask the developer for the `id`** and write it as an explicit
+  literal — `AUTO_INCREMENT` must never assign it (silent per-environment drift breaks every
+  hardcoded reference). Conversely these `id`s **should** be hardcoded wherever referenced,
+  including foreign keys (`recordId`, `recordFieldId`) from client databases and in PHP query
+  strings. This is what makes *Database isolation* workable — no client migration needs to read
+  `Core` to resolve a `recordFieldId`. Enforced by the `dbchanges2-record-ids` hook. (jcardinal)
+- 2026-07-31 — **Added *Database isolation — never query across databases* (HARD RULE) + rule #8.**
   A `dbchanges2` `.sql` file may only reference tables in the one database its folder targets, and
   must reference them unqualified; fan-out folders (`Client/`, `Logs_Client/`, `_modules/`) permit
   no database qualifier at all. Rationale: in production `Core`, `Client_<Tenant>`,

package/knowledge/2.0/standards/framework-rules.md

@@ -137,6 +137,30 @@ Enforced mechanically by the `PreToolUse` hook
 examples, and the approved rewrites: `2.0/apps/dbchanges2/architecture.md` → *Database
 isolation*. **Applies to `dbchanges2` only — the 1.0 `dbchanges` repo is exempt.**
 
+### `Core.Records` / `Core.RecordFields` — the only hardcoded `id`s on the platform
+
+**These two tables, and only these two, have team-maintained primary keys.** Their `id` values are
+**stable platform-wide constants**, identical in every environment, and the next available value is
+tracked by the team **in the developer chat**. No other table on the platform may have a hardcoded
+`id`.
+
+**Inserting into them — ask first.** When a change inserts a row into `Core.Records` or
+`Core.RecordFields`, **stop and ask the developer for the next `id`**, then write it as an explicit
+literal. **Never let `AUTO_INCREMENT` assign it** — the column is still defined that way, but it is
+not the source of truth, and a value it picks silently drifts between environments and invalidates
+every hardcoded reference to that row. The `id` must be reserved by a human, so it cannot be
+guessed or derived — asking is mandatory.
+
+**Referencing them — hardcode the `id`.** Anywhere these rows are referenced, and anywhere a
+**foreign key** points at them (`recordId`, `recordFieldId`, and equivalents), use the numeric
+literal rather than a lookup — including in SQL embedded in PHP in `worker2` / `api2` /
+`_underscore`. Always add a comment naming the record/field the number refers to; a bare `4188` is
+unverifiable later.
+
+This is also what makes the `dbchanges2` isolation rule above workable: a `Client_<Tenant>` change
+never has to read `Core` to resolve a `recordFieldId`. Full detail and examples:
+`2.0/apps/dbchanges2/architecture.md` → *`Core.Records` / `Core.RecordFields`*.
+
 ## Checking dependencies before touching shared code
 
 `dependsOn` in `knowledge/registry.json` means a repo extends or depends on another repo's classes. Before modifying a class in a dependency repo (e.g. `_underscore` core):

package/knowledge/sessions/2026-07-31-true-80494-fulfill-ship-hotfix-mhammontree.md

@@ -0,0 +1,108 @@
+---
+type: session
+slug: true-80494-fulfill-ship-hotfix
+title: TRUE-80494 Fulfill & Ship submit-blocker hotfix + Reference 1/2 carrier pass-through + beta metadata repairs
+author: mhammontree
+repos: [toga2-supply, _underscore, dbchanges2, api2]
+framework: "2.0"
+client: growrk
+status: active
+created: 2026-07-31
+updated: 2026-07-31
+---
+
+# Session: true-80494-fulfill-ship-hotfix
+**Date:** 2026-07-31
+**Project/Repo:** toga2-supply (2.0) + _underscore / dbchanges2 / api2
+**Task:** Root-cause why Fulfill & Ship stopped working in production for GroWrk after the TRUE-79191 deploy (2026-07-29), ship the TRUE-80494 hotfix, wire the Reference 1/2 fields through to the carrier so they print on shipping labels, and repair the beta/dev-sandbox metadata gaps blocking an end-to-end test.
+
+---
+
+## What WORKED
+
+- **ROOT CAUSE of the prod outage — proven, not inferred.** Clicking Fulfill & Ship fired **no network request at all** (empty Network tab). Cause: `DUMMYUPDATESHIPMENTFIELDS.json:189-201` has a **display-only** section header (id 31, "Address") with `valueKey: ""` + `isRequired: true`. `validateFormOnSubmit.ts:37-44` does `getValues(field.valueKey)`; react-hook-form's `get` short-circuits on a falsy path so `getValues("")` is **always** `undefined` → `hasErrors = true` on **every** submit. Field 31 is **pre-existing** (confirmed via `git show b6cb3b426^`) and was harmless because the caller filtered blank keys. CodeRabbit batch 2 (`ba611989a`) broke it:
+  ```diff
+  - let hasErrors = actualErrors.length > 0;                        // "" filtered out → harmless
+  + let hasErrors = validationHasErrors || actualErrors.length > 0; // raw boolean → always true
+  ```
+  The early `return` is silent: the error is keyed on `""` and that field renders through `BaseInput`'s `case "none"` branch (a bare `<p>`, no error slot), so nothing displays. **Blast radius: all clients, and all three actions** (Fulfill & Ship, Save, Save & Create New Shipment) — `onFormSubmit` gates all of them. Why local testing passed on 07-27: tracking number 9676 was saved **before** `ba611989a` existed.
+- **The fix works — confirmed by the developer in prod-branch local.** Reverted only the caller in `EditShipmentForm.tsx:592` back to `actualErrors.length > 0` and dropped the now-unused `const validationHasErrors =`. Buttons work again and validation correctly blocks on an empty weight field. `npx tsc --noEmit` clean.
+- **`dbchanges2` RecordFields id corrections — committed `5447f68`.** `2434 → 2480` (returnAddressId) and `2435 → 2481` (signatureType), matching what production actually holds.
+- **`api2` `label_format = "PNG"` added to `Config/production.ini` — committed `851c227`.** Without it prod UPS defaults to ZPL while the return-label path expects a raster PNG for FPDF. `beta.ini` already had it, which is exactly why beta worked and prod didn't.
+- **Reference 1/2 → carrier pass-through implemented** (uncommitted). Verified the transport mechanism first: these are **RecordScripts** (`Core.RecordScripts`), dispatched at `api2/Component/Api/V2/V2.php:4202` via `parse_str($_SERVER['QUERY_STRING'], $args)` then `$model::$method(...$args)` — PHP **named-argument unpacking**, so query-string keys bind to parameter names. `Core.RecordScripts` stores only `(recordId, method, route, phpMethod)` — no parameter signature — so **no migration is needed** to add params.
+- **UPS label fix identified and implemented.** `Ups.php` was putting the reference into `Request.TransactionReference.CustomerContext`, which is UPS's request/response **correlation echo** — it never prints on a label. Replaced with real **package-level** `ReferenceNumber` entries via a new `buildPackageReferenceNumbers()` helper, wired into **both** payload builders (OAuth + legacy), following the existing `DCISType` conditional pattern. FedEx was already correct (`customerReferences`), just needed a second entry.
+- **Carrier codes verified against docs** (web lookup): UPS `PO` = Purchase Order Number, `TN` = Transaction Reference Number, plus AJ/AT/BM/9V/ON/DP/3Q/IK/MK/MJ/PM/PC/RQ/RZ/SA/SE/ST/EI/TJ/SY. **UPS max 2 reference numbers, 35 chars each.** UPS prints the code's *meaning* next to the value. FedEx `customerReferenceType` accepts CUSTOMER_REFERENCE / P_O_NUMBER / INVOICE_NUMBER / DEPARTMENT_NUMBER / BILL_OF_LADING / RMA_ASSOCIATION / STORE_NUMBER / ELECTRONIC_PRODUCT_CODE / SHIPMENT_INTEGRITY / INTRACOUNTRY_REGULATORY_REFERENCE, **max 3 per package**, and rejects two entries of the same type.
+- **All `php -l` clean; `tsc --noEmit` clean; JSON valid.**
+- **BETA (= dev-sandbox cluster) METADATA REPAIRS — all applied and verified this session:**
+  1. **Empty unit dropdowns fixed.** `Client_Growrk` (dev-sandbox) had `lengthMeasureId` (2476) and `weightMeasureId` (2477) granted to **role 3 only**, and `measureType` (2478) with **zero** grant rows. Ungranted = the V2 engine omits the field from `GET /v2/measures` (200, no error), so the frontend's `measureType === "LENGTH"` split returned empty arrays. Final verified state: 2476 → roles 1,3; 2477 → roles 1,3; 2478 → role 1. Dropdowns now show `in`/`lb`.
+  2. **Save fixed (`EV-10`, "Column 'itemFulfillmentStageId' cannot be null").** `_Model_Client_ItemFulfillment::prePost()` defaults the stage to *shipped*, but it is **not called directly** — the V2 engine dispatches it from an `ApiPayloadInterceptors` registration, deriving the method as `strtolower('PRE') . ucfirst(strtolower('POST'))` → `prePost`. dev-sandbox `Core` was missing the `PRE`/`POST` row for recordId 28. Applied `Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql`; verified present and active. **Full-table drift check: that was the ONLY interceptor missing** — the other 8 match prod exactly. Stages themselves were already seeded (picked/packed/shipped).
+  3. **Tracking-number save fixed (`EV-8`, field `signatureType` does not exist).** dev-sandbox had neither the Core RecordField nor the column. Registered the field **omitting `id`** so auto_increment assigned it → landed at **2764**; added the `VARCHAR(255) utf8mb4` column `AFTER requiresSignature`; granted by mirroring `containsBattery` (field **962**). Verified: 2764 → roles 1 and 3.
+- **Identified that "beta" reads dev-sandbox.** `toga2-supply/.env` → `VITE_API=https://api.beta.togahub.com/v2`; `api2/Config/beta.ini` `[database] hostname = dev.sandbox.database.togahub.com`. `Core` and `Client_Growrk` are on the **same cluster** in dev-sandbox, so `Core.`-qualified references in `Client/` migrations resolve there (in prod they are split across `prod-core`/`prod-client`).
+
+## What did NOT work — DO NOT RETRY THESE
+
+- **The ACL/missing-migration theory for the PROD outage — FALSIFIED.** Every UoM grant, column, and seed row is present in prod `Client_Growrk` (2476/2477/2478 all role 1, `Measures.measureType` + `conversionFactorToBase`, Inch/Pound seeded, `TrackingNumbers` FK columns), and bridge records 317-322 each have their `AclLogicGroups` + `AclLogicGroupExpressions`. Do not re-investigate prod ACL for this bug.
+- **Assuming the frontend/backend wasn't deployed — WRONG.** All four CodeRabbit commits (`e91f7029d`, `d1eba64af`, `ba611989a`, `e0942cb4f`) are on `toga2-supply` `_production` via PR #585, and `77fae34c` is on `_underscore` `_production` via PR #691. **The deployed code was precisely the problem.**
+- **Shipping `dbchanges2` `3bc5e5b` as written — WRONG.** It asserts `signatureType = 2482`, but prod 2482 is already `entitlements.serviceAddressId` (TRUE-79533). Prod actually holds returnAddressId=2480 and signatureType=**2481**. Corrected to 2481 in `5447f68`.
+- **Crediting `_underscore/Route.php` with the query-param → argument binding — WRONG.** `Route.php:46` builds `$routeVars` from `explode('/', urldecode($route))` — **path segments, not the query string**. The real dispatcher is the RecordScripts path in `api2/Component/Api/V2/V2.php:4202`.
+- **Running `Client/2026-07-22c` in chunks / as a partial selection — SILENTLY HALF-APPLIES.** Its `@measuresSlugFieldId` / `@measureTypeFieldId` are `SET` *after* the first two INSERTs, so a chunked execution skips the measureType block, and `WHERE sibling.recordFieldId = NULL` matches nothing → **0 rows, no error**. This has now cost two debugging rounds (prod originally, dev-sandbox today). Fix by running the whole file in one batch, or use the inlined-subselect form.
+- **Running the shipped `Core/2026-07-10a` / `Core/2026-07-16a` on dev-sandbox — WILL FAIL.** They hardcode ids 2480/2481, which in dev-sandbox belong to `vocabularies.id` / `vocabularies.uuid` (dev-sandbox `MAX(RecordFields.id)` was 2763; `isFulfillable` is 2615 there vs 2434 in prod). Ids genuinely diverge per environment. Omit `id` and let auto_increment assign instead.
+- **Testing `_underscore` changes from local against beta — IMPOSSIBLE as configured.** The local Vite server supplies only the frontend; every API call goes to the **deployed** beta api2 + `_underscore`. Local `_underscore` edits are not in the request path. The developer pushed TRUE-80494 `_underscore` to beta to work around this.
+- **Mirroring `needsReturnLabel` for grants** — its grants don't exist in every client (Client_True had none) → ungranted fields → EV-9. Mirror `shippingMethodId` (338) / `slug` (723) / `containsBattery` (962) / `shipToAddressId` (991) instead.
+- **Re-running `Client/2026-07-22b`** — one-time backfill; a re-run coerces later NULL rows to Inch/Pound.
+- **Initially mapping Reference 1 = PO / Reference 2 = SO — REVERSED.** The field-config placeholders are Reference 1 → `"e.g. NetSuite Sales Order #"` and Reference 2 → `"e.g. NetSuite Purchase Order #"`. Code now follows the UI.
+- **`Measures.customerPurchaseOrder` as a PO source** — in GroWrk that column holds **people's names** ("Butch Dority", "Robin Rigg") on old rows only (id ≤ 7524) and is NULL on all recent orders. It is not a PO field. (It was the hardcoded source in `ItemFulfillment.php` for the carrier reference — now replaced.)
+- **A `toga_query` containing the word "grant" in a string literal** is rejected by the MCP tool's keyword guard ("Forbidden keyword 'GRANT'"). Rename the label.
+
+## Not tried yet (candidates for next session)
+
+- **THE ACTUAL END-TO-END BETA TEST — interrupted mid-run.** The developer had a disposable SO ready and was retrying the tracking-number save right after the `signatureType` repair landed. Not yet done: fulfill, inspect the label, confirm NetSuite.
+- **`returnAddressId` Core registration + grant on dev-sandbox.** SQL fully prepared and dependency-checked (mirror `shipToAddressId` field **991**, `childPolicy = 'CREATE'`, `type = NULL`, uuid `c3a1f2d4-5e6b-4c7a-9d8e-0f1a2b3c4d5e`, omit `id` → expect 2765). Only needed if testing return labels. The **column already exists** in dev-sandbox; only the Core row + grant are missing.
+- **Hardening `Client/2026-07-22c`** (and `2026-07-16b`) to inline subselects instead of session variables so a partial execution fails loudly instead of silently.
+- **Deciding whether the references belong on the RETURN label.** `ItemFulfillment.php:1468` (`generateReturnLabel`) still uses `$salesOrder->customerPurchaseOrder`. Deliberately left unchanged — it's the return leg to the warehouse, a product decision, not mechanical.
+- **Confirming the Reference 1/2 semantic order with Eric/Skyler.** If Eric actually types the PO into Reference 1, the labels print the wrong descriptors — a two-line constant swap in `Ups.php` and `Fedex.php`.
+- **Committing `toga2-supply` + `_underscore`** — both working trees are dirty on TRUE-80494.
+- **Latent second silent-abort path:** `checkDimensions.ts:6` dereferences `formValues.dimensions.length` unguarded, and `handleFulfillAndShip` (`EditShipmentForm.tsx:770-772`) calls `onFormSubmit` without `await`/`.catch()` — a `TypeError` becomes an unhandled rejection with the same "nothing happens" symptom. Deserves its own ticket.
+- **Dynamic weight symbol** on Pending Shipments cards is still a static `"lbs."`.
+
+## Current file state
+
+| File | Status | Notes |
+|------|--------|-------|
+| `toga2-supply` `src/pages/EditShipment/view/components/forms/EditShipmentForm.tsx` | modified, **uncommitted** | Submit-guard revert (the outage fix) + `reference1`/`reference2` in `defaultValues` + passed into `fulfillShipment()` |
+| `toga2-supply` `src/pages/EditShipment/api/UpdateShipmentApi.ts` | modified, **uncommitted** | `fulfillShipment()` takes both references, URL-encodes them onto the query string |
+| `toga2-supply` `src/pages/EditShipment/types.ts` | modified, **uncommitted** | `reference1?`/`reference2?` on `ShipmentData` |
+| `toga2-supply` `.../FIELDS/DUMMYUPDATESHIPMENTFIELDS.json` | modified, **uncommitted** | `"characterLimit": 35` on both reference fields (UPS cap) |
+| `_underscore` `Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php` | modified, **uncommitted** | Added `$referenceString2` |
+| `_underscore` `Component/Library/Carriers/Ups/Ups.php` | modified, **uncommitted** | New `buildPackageReferenceNumbers()`; package-level `ReferenceNumber` in **both** payload builders; code constants TN/PO |
+| `_underscore` `Component/Library/Carriers/Fedex/Fedex.php` | modified, **uncommitted** | Two `customerReferences` entries; PRIMARY=CUSTOMER_REFERENCE, SECONDARY=P_O_NUMBER; `MAX_CUSTOMER_REFERENCES = 3` |
+| `_underscore` `Model/Client/ItemFulfillment.php` | modified, **uncommitted** | Optional `$reference1`/`$reference2` on `fedexShipmentApi` + `upsShipmentApi`; the **two outbound** sites (763-764, 1251-1252) now use them. Return-label site (1468) intentionally untouched |
+| `dbchanges2` `Core/2026-07-10a - ItemFulfillmentReturnAddressIdRecordField.sql` | **committed `5447f68`** | id 2434 → 2480 |
+| `dbchanges2` `Core/2026-07-16a - TrackingNumberSignatureTypeRecordField.sql` | **committed `5447f68`** | id 2435 → 2481 (NOT 2482 — that's `entitlements.serviceAddressId`) |
+| `api2` `Config/production.ini` | **committed `851c227`** | `label_format = "PNG"` under `[ups]` |
+| dev-sandbox `Core` | **DB changed** | `ApiPayloadInterceptors` PRE/POST for recordId 28; `RecordFields` signatureType @ **2764** |
+| dev-sandbox `Client_Growrk` | **DB changed** | measure grants completed (2476/2477 role 1, 2478 role 1); `TrackingNumbers.signatureType` column; signatureType grants (roles 1,3) |
+| `_underscore` beta deploy | pushed by developer | TRUE-80494 pushed to beta so the carrier changes are in the request path |
+
+## Decisions made
+
+- **Revert only the caller, not the validation helpers.** `validateFormOnSubmit` and `checkDimensions` keep returning booleans, because reverting them would destroy CodeRabbit **batch 3** (`e0942cb4f`), a genuinely correct `clearErrors` fix. Rejected: full revert of `ba611989a`.
+- **Chose the revert over hardening the validator.** Developer's explicit call. Noted risk: it restores the first-submit-slips-through behaviour CodeRabbit flagged, and CodeRabbit will likely re-flag it. The alternative (skip fields with `!field.valueKey || inputType === "none"` inside the validator, keeping both fixes) is written into the plan file but **not applied**.
+- **No `dbchanges2` work for the reference feature.** Skyler confirmed the values are user-entered, not stored and not prefilled from NetSuite — so no columns, no `Core.RecordFields`, no `AclFieldPermissions`. Rejected: the earlier full-stack persist-and-recall design.
+- **UPS references at PACKAGE level, not shipment level.** UPS rejects `Shipment.ReferenceNumber` on US/PR→US/PR domestic shipments, which is most GroWrk volume.
+- **Reference 1 = sales order → UPS `TN` / FedEx `CUSTOMER_REFERENCE`; Reference 2 = purchase order → UPS `PO` / FedEx `P_O_NUMBER`.** Driven by the form placeholders (the UI is what Eric follows), and kept consistent across carriers so a label reads the same either way. `TN` chosen over `ON` (Dealer Order Number) because UPS prints the code's meaning and `ON` would be misleading — UPS has no sales-order code.
+- **Enforce the 35-char UPS cap on the form** via the existing `characterLimit` mechanism (visible RHF message) rather than truncating server-side. Silent truncation would print wrong data on a label; a visible form error is recoverable.
+- **On dev-sandbox, omit `id` on `RecordFields` inserts** and let auto_increment assign, instead of adapting the hardcoded prod ids. Removes the whole class of collision.
+- **Reuse prod uuids for the dev-sandbox metadata rows** so environments stay comparable (verified free before inserting).
+- **Left `generateReturnLabel` unchanged** — return-leg references are a product decision, and the plan listed line 1468 before we knew it was the return path.
+
+## Blockers
+
+None technical. The developer was pulled to a more urgent task mid-test; the beta end-to-end run is incomplete. All known metadata gaps blocking the *save* path are fixed; `returnAddressId` remains unregistered on dev-sandbox and will surface as `EV-8` **only** if the return-label flow is exercised.
+
+## Exact next step
+
+> On beta (`growrk.togasupply:5173/edit-shipment?internalId=7221433`, or the disposable SO), retry the tracking-number save — it should now succeed with `signatureType` registered at 2764. Then fill both Reference fields, weight, and all three dimensions, click Fulfill & Ship, and **inspect the returned label image** for both reference values and which descriptor sits next to which ("Purchase Order" must be beside the Reference 2 value). A successful API response proves nothing here — UPS previously accepted the reference into `CustomerContext` and printed nothing. Be aware `beta.ini` and `production.ini` point at the **same NetSuite account (1095849)**, so the fulfillment writes to production NetSuite.
+
+---
+_Saved by /session-save on 2026-07-31_

package/package.json

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

package/scripts/hooks/dbchanges2-cluster-isolation.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * dbchanges2-cluster-isolation.js — DETERMINISTIC enforcement of the dbchanges2
+ * single-database rule.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * In production, the 2.0 databases are NOT on one server. Core, Client_<Tenant>,
+ * Archive_<Tenant>, Logs/Logs_<Tenant>, and Cache each live on an ENTIRELY
+ * SEPARATE cluster. A query that joins or sub-selects across those names is
+ * physically impossible in production — it cannot resolve the foreign schema.
+ *
+ * Locally and in non-prod every database happens to sit behind one endpoint, so a
+ * cross-database query runs fine there and the migration looks correct right up
+ * until it reaches production and dies. That silent local success is exactly why
+ * prose alone was not enough and this check is mechanical.
+ *
+ * THE RULE (hard, no exceptions)
+ * ------------------------------
+ * A .sql file in dbchanges2 may only reference tables in the ONE database its
+ * folder targets. References to that database are UNQUALIFIED. Any qualified
+ * `OtherDatabase.Table` reference is a violation — including in fan-out folders
+ * (Client/, Logs_Client/, _modules/), where the database name varies per tenant
+ * and therefore NOTHING may be qualified.
+ *
+ * Instead of reading a foreign database to resolve an id, use a hardcoded v4 UUID
+ * literal, a slug/natural key that exists inside the target database, or split the
+ * work into one file per database folder.
+ *
+ * SCOPE
+ * -----
+ * Only .sql files under a dbchanges2 checkout. The 1.0 `dbchanges` repo is
+ * explicitly NOT affected (its path is excluded). Every other write passes
+ * through untouched.
+ *
+ * Fail-open: any internal/parse error allows the write. A crashing guard must
+ * never brick editing.
+ *
+ * Escape hatch (false positives ONLY, not for writing cross-database SQL):
+ *   DBCHANGES2_ISOLATION_DISABLED=1
+ */
+
+const fs = require('fs');
+
+/* ---------- input: read stdin JSON (CC standard), fall back to env ---------- */
+function readPayload() {
+  let raw = '';
+  try { raw = fs.readFileSync(0, 'utf8'); } catch (e) { /* no stdin */ }
+  let data = {};
+  if (raw && raw.trim()) {
+    try { data = JSON.parse(raw); } catch (e) { data = {}; }
+  }
+  if (!data.tool_name && process.env.CLAUDE_TOOL_NAME) data.tool_name = process.env.CLAUDE_TOOL_NAME;
+  if (!data.tool_input && process.env.CLAUDE_TOOL_INPUT) {
+    try { data.tool_input = JSON.parse(process.env.CLAUDE_TOOL_INPUT); } catch (e) {}
+  }
+  return data;
+}
+
+/* Known 2.0 database families. We match against this bounded set rather than a
+ * generic `x.y` pattern so ordinary table aliases (`rf.id`, `sibling.roleId`)
+ * never trip the check. */
+const DB_FAMILIES = ['Core', 'Client', 'Logs', 'Archive', 'Cache', 'Team'];
+
+/* Strip comments and string literals so a database name mentioned in prose or in
+ * a quoted value is not reported as a reference. Newlines are preserved so the
+ * reported line numbers still match the original file. */
+function stripNonCode(sql) {
+  const blanked = (m) => m.replace(/[^\n]/g, ' ');
+  return sql
+    .replace(/\/\*[\s\S]*?\*\//g, blanked)   // /* block comments */
+    .replace(/(^|[^\w$])#[^\n]*/g, (m) => m[0] === '#' ? blanked(m) : m[0] + blanked(m.slice(1)))
+    .replace(/--[ \t][^\n]*/g, blanked)      // -- line comments (MySQL needs the space)
+    .replace(/'(?:\\.|''|[^'\\])*'/g, blanked) // 'string literals'
+    .replace(/"(?:\\.|""|[^"\\])*"/g, blanked); // "string literals"
+}
+
+/* Resolve which database a file targets from its folder, and whether that folder
+ * fans out across tenants (in which case no qualifier at all is permitted). */
+function resolveTarget(filePath) {
+  const norm = filePath.replace(/\\/g, '/');
+  const m = norm.match(/\/dbchanges2\/(.+)$/i);
+  if (!m) return null;
+  const rel = m[1];
+  const seg = rel.split('/')[0];
+  if (!seg || seg === rel) return null;               // file sits at repo root, no DB folder
+  if (/^_modules$/i.test(seg)) {
+    return { folder: seg, db: null, fanout: true, why: 'a module change-set applied inside each opted-in client database' };
+  }
+  if (/^Client$/i.test(seg)) {
+    return { folder: seg, db: null, fanout: true, why: 'fan-out to every Client_<Tenant> database' };
+  }
+  if (/^Logs_Client$/i.test(seg)) {
+    return { folder: seg, db: null, fanout: true, why: 'fan-out to every Logs_<Tenant> database' };
+  }
+  return { folder: seg, db: seg, fanout: false, why: 'the ' + seg + ' database only' };
+}
+
+/* Find every qualified reference to a known database family. */
+function findQualifiedRefs(sql) {
+  const code = stripNonCode(sql);
+  const names = DB_FAMILIES.join('|');
+  // `Core`.`Records` / Core.Records / Client_Aig.SalesOrders / USE Core
+  const re = new RegExp(
+    '`?\\b((?:' + names + ')(?:_[A-Za-z0-9]+)?)`?\\s*\\.\\s*`?[A-Za-z_][A-Za-z0-9_]*`?',
+    'g'
+  );
+  const useRe = new RegExp('\\bUSE\\s+`?((?:' + names + ')(?:_[A-Za-z0-9]+)?)`?', 'gi');
+  const found = [];
+  const push = (index, db, text) => {
+    const line = code.slice(0, index).split('\n').length;
+    found.push({ line, db, text: text.trim() });
+  };
+  let hit;
+  while ((hit = re.exec(code)) !== null) push(hit.index, hit[1], hit[0]);
+  while ((hit = useRe.exec(code)) !== null) push(hit.index, hit[1], hit[0]);
+  return found;
+}
+
+function main() {
+  if (process.env.DBCHANGES2_ISOLATION_DISABLED === '1') return;
+
+  const data = readPayload();
+  const tool = data.tool_name || '';
+  if (!/^(Write|Edit|MultiEdit)$/.test(tool)) return;
+
+  const input = data.tool_input || {};
+  const filePath = typeof input.file_path === 'string' ? input.file_path : '';
+  if (!/\.sql$/i.test(filePath)) return;
+
+  const target = resolveTarget(filePath);
+  if (!target) return;                                  // not a dbchanges2 .sql file (1.0 dbchanges excluded)
+  if (/\/HISTORIC\//i.test(filePath.replace(/\\/g, '/'))) return; // archive, never executed
+
+  // Gather the SQL this call would introduce, across all three tool shapes.
+  let sql = '';
+  if (typeof input.content === 'string') sql += input.content + '\n';
+  if (typeof input.new_string === 'string') sql += input.new_string + '\n';
+  if (Array.isArray(input.edits)) {
+    for (const e of input.edits) {
+      if (e && typeof e.new_string === 'string') sql += e.new_string + '\n';
+    }
+  }
+  if (!sql.trim()) return;
+
+  const violations = findQualifiedRefs(sql).filter((v) => {
+    if (target.fanout) return true;                     // no qualifier is ever valid here
+    return v.db.toLowerCase() !== target.db.toLowerCase();
+  });
+  if (!violations.length) return;
+
+  const lines = [];
+  lines.push('BLOCKED by dbchanges2 database isolation — this SQL reads across a database boundary.');
+  lines.push('');
+  lines.push('  File:   ' + filePath);
+  lines.push('  Folder: ' + target.folder + '/  → targets ' + target.why);
+  lines.push('');
+  lines.push('  Foreign reference' + (violations.length === 1 ? '' : 's') + ':');
+  for (const v of violations.slice(0, 20)) {
+    lines.push('    line ' + v.line + ': ' + v.text + '   ← ' + v.db + ' is a different database');
+  }
+  if (violations.length > 20) lines.push('    … and ' + (violations.length - 20) + ' more');
+  lines.push('');
+  lines.push('In PRODUCTION, Core / Client_<Tenant> / Archive_<Tenant> / Logs / Cache are on');
+  lines.push('ENTIRELY SEPARATE CLUSTERS. This query cannot resolve there — it only appears to');
+  lines.push('work locally and in non-prod, where every database shares one endpoint.');
+  lines.push('');
+  if (target.fanout) {
+    lines.push('This folder fans out across tenants, so the database name is not fixed:');
+    lines.push('reference tables UNQUALIFIED only — no database prefix at all.');
+  } else {
+    lines.push('Reference only tables in ' + target.db + ', and reference them UNQUALIFIED.');
+  }
+  lines.push('');
+  lines.push('Rewrite it without the cross-database read:');
+  lines.push('  • hardcode a pre-generated v4 UUID literal instead of SELECTing an id;');
+  lines.push('  • resolve rows by a slug / natural key that exists in the target database;');
+  lines.push('  • split the work into one file per database folder.');
+  lines.push('');
+  lines.push('See knowledge/2.0/apps/dbchanges2/architecture.md → "Database isolation".');
+  lines.push('(The 1.0 dbchanges repo is not subject to this rule.)');
+  // A PreToolUse deny (exit 2) surfaces its reason from STDERR — writing to stdout
+  // blocks the call but shows the agent nothing, so the explanation is lost.
+  process.stderr.write(lines.join('\n') + '\n');
+  process.exit(2);
+}
+
+try { main(); } catch (e) { /* fail-open */ }

package/scripts/hooks/dbchanges2-record-ids.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * dbchanges2-record-ids.js — DETERMINISTIC enforcement of the team-maintained
+ * primary keys on Core.Records and Core.RecordFields.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * These two tables are the ONLY tables on the 2.0 platform whose `id` is a
+ * team-maintained constant. The next available value is tracked by the team in the
+ * developer chat, and the same row carries the same `id` in every environment —
+ * which is what lets every other database (and PHP query) hardcode `recordId` /
+ * `recordFieldId` instead of joining out to Core.
+ *
+ * If a migration omits `id` and lets MySQL's AUTO_INCREMENT assign one, the value
+ * differs per environment. Nothing fails at run time: the insert succeeds, and
+ * every hardcoded reference to that row silently points at the wrong record or at
+ * nothing. That is unrecoverable without a manual audit, so it has to be caught
+ * before the file is written.
+ *
+ * THE RULE
+ * --------
+ * An INSERT/REPLACE into Records or RecordFields must assign `id` explicitly.
+ * The developer must be ASKED for the value first — it cannot be derived, so this
+ * hook deliberately offers no way to satisfy it automatically.
+ *
+ * SCOPE
+ * -----
+ * .sql files under dbchanges2 whose folder targets Core (or which reference the
+ * tables Core-qualified). The 1.0 `dbchanges` repo is NOT affected. Sibling tables
+ * whose names merely END in RecordFields (CustomRecordFields, SectionRecordFields)
+ * are NOT covered — only the two exact tables.
+ *
+ * Fail-open on any internal error.
+ *
+ * Escape hatch (false positives ONLY): DBCHANGES2_RECORD_IDS_DISABLED=1
+ */
+
+const fs = require('fs');
+
+function readPayload() {
+  let raw = '';
+  try { raw = fs.readFileSync(0, 'utf8'); } catch (e) { /* no stdin */ }
+  let data = {};
+  if (raw && raw.trim()) {
+    try { data = JSON.parse(raw); } catch (e) { data = {}; }
+  }
+  if (!data.tool_name && process.env.CLAUDE_TOOL_NAME) data.tool_name = process.env.CLAUDE_TOOL_NAME;
+  if (!data.tool_input && process.env.CLAUDE_TOOL_INPUT) {
+    try { data.tool_input = JSON.parse(process.env.CLAUDE_TOOL_INPUT); } catch (e) {}
+  }
+  return data;
+}
+
+/* Blank out comments and string literals, preserving newlines so reported line
+ * numbers still line up with the original file. */
+function stripNonCode(sql) {
+  const blanked = (m) => m.replace(/[^\n]/g, ' ');
+  return sql
+    .replace(/\/\*[\s\S]*?\*\//g, blanked)
+    .replace(/(^|[^\w$])#[^\n]*/g, (m) => (m[0] === '#' ? blanked(m) : m[0] + blanked(m.slice(1))))
+    .replace(/--[ \t][^\n]*/g, blanked)
+    .replace(/'(?:\\.|''|[^'\\])*'/g, blanked)
+    .replace(/"(?:\\.|""|[^"\\])*"/g, blanked);
+}
+
+/* Which database does this file's folder target? */
+function targetDb(filePath) {
+  const norm = filePath.replace(/\\/g, '/');
+  const m = norm.match(/\/dbchanges2\/(.+)$/i);
+  if (!m) return null;
+  const seg = m[1].split('/')[0];
+  if (!seg || seg === m[1]) return null;
+  return seg;
+}
+
+/* Find INSERT/REPLACE statements targeting the two protected tables and report any
+ * that do not assign `id`. */
+function findUnassignedIds(sql) {
+  const code = stripNonCode(sql);
+  // (?<![A-Za-z0-9_`]) prevents matching CustomRecordFields / SectionRecordFields.
+  const re = /\b(?:INSERT(?:\s+IGNORE)?|REPLACE)\s+INTO\s+(?:`?Core`?\s*\.\s*)?`?(?<![A-Za-z0-9_])(Records|RecordFields)`?/gi;
+  const found = [];
+  let hit;
+  while ((hit = re.exec(code)) !== null) {
+    const table = hit[1];
+    const after = code.slice(hit.index + hit[0].length, hit.index + hit[0].length + 2000);
+    let assignsId = false;
+
+    // Form A: INSERT INTO t (col, col, ...) VALUES/SELECT ...
+    const colList = after.match(/^\s*\(([\s\S]*?)\)/);
+    if (colList) {
+      assignsId = colList[1]
+        .split(',')
+        .map((c) => c.trim().replace(/`/g, '').toLowerCase())
+        .includes('id');
+    } else {
+      // Form B: INSERT INTO t SET id = 4188, ...
+      const setClause = after.match(/^\s*SET\b([\s\S]*?)(?:;|$)/i);
+      if (setClause) assignsId = /(^|[\s,`])id\s*=/i.test(setClause[1]);
+      // Form C: INSERT INTO t SELECT ... — no column list, cannot verify; treat as
+      // unassigned so it gets a human look.
+    }
+
+    if (!assignsId) {
+      found.push({
+        line: code.slice(0, hit.index).split('\n').length,
+        table,
+        text: hit[0].replace(/\s+/g, ' ').trim(),
+      });
+    }
+  }
+  return found;
+}
+
+function main() {
+  if (process.env.DBCHANGES2_RECORD_IDS_DISABLED === '1') return;
+
+  const data = readPayload();
+  if (!/^(Write|Edit|MultiEdit)$/.test(data.tool_name || '')) return;
+
+  const input = data.tool_input || {};
+  const filePath = typeof input.file_path === 'string' ? input.file_path : '';
+  if (!/\.sql$/i.test(filePath)) return;
+
+  const db = targetDb(filePath);
+  if (!db) return;                                                 // not a dbchanges2 .sql file
+  if (/\/HISTORIC\//i.test(filePath.replace(/\\/g, '/'))) return;  // archive, never executed
+
+  let sql = '';
+  if (typeof input.content === 'string') sql += input.content + '\n';
+  if (typeof input.new_string === 'string') sql += input.new_string + '\n';
+  if (Array.isArray(input.edits)) {
+    for (const e of input.edits) {
+      if (e && typeof e.new_string === 'string') sql += e.new_string + '\n';
+    }
+  }
+  if (!sql.trim()) return;
+
+  // Records/RecordFields live in Core. Only inspect files that target Core, or that
+  // name the tables Core-qualified (the isolation hook handles the latter's legality).
+  if (!/^Core$/i.test(db) && !/`?Core`?\s*\.\s*`?(Records|RecordFields)\b/i.test(stripNonCode(sql))) return;
+
+  const violations = findUnassignedIds(sql);
+  if (!violations.length) return;
+
+  const out = [];
+  out.push('BLOCKED: insert into ' + violations.map((v) => v.table).filter((t, i, a) => a.indexOf(t) === i).join(' / ') +
+    ' without an explicit `id`.');
+  out.push('');
+  out.push('  File: ' + filePath);
+  for (const v of violations.slice(0, 20)) {
+    out.push('    line ' + v.line + ': ' + v.text + '   ← no `id` assigned');
+  }
+  if (violations.length > 20) out.push('    … and ' + (violations.length - 20) + ' more');
+  out.push('');
+  out.push('Core.Records and Core.RecordFields are the ONLY two tables on the platform with');
+  out.push('TEAM-MAINTAINED primary keys. The next available id is tracked by the team in the');
+  out.push('developer chat, and the same row must carry the same id in EVERY environment —');
+  out.push('that is what lets other databases hardcode recordId / recordFieldId instead of');
+  out.push('joining out to Core.');
+  out.push('');
+  out.push('Letting AUTO_INCREMENT assign the id fails silently: the insert succeeds, the id');
+  out.push('differs per environment, and every hardcoded reference to that row then points at');
+  out.push('the wrong record or at nothing.');
+  out.push('');
+  out.push('REQUIRED: ask the developer what the next id value(s) are, then write them as');
+  out.push('explicit literals and note in a comment that the team assigned them:');
+  out.push('');
+  out.push('    # id 4188 assigned by the team (developer chat)');
+  out.push('    INSERT INTO RecordFields (id, uuid, recordId, `field`)');
+  out.push("    VALUES (4188, '<v4 uuid literal>', 219, 'serviceAddressId');");
+  out.push('');
+  out.push('This value cannot be derived or guessed — you must ask.');
+  out.push('See knowledge/2.0/apps/dbchanges2/architecture.md → "Core.Records / Core.RecordFields".');
+  // exit 2 surfaces the reason from STDERR; stdout would block silently.
+  process.stderr.write(out.join('\n') + '\n');
+  process.exit(2);
+}
+
+try { main(); } catch (e) { /* fail-open */ }