toga-ai 1.0.443 → 1.0.445

package/knowledge/1.0/apps/togadesk/INDEX.md

@@ -3,11 +3,12 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [TOGa Desk Architecture](architecture.md) | TOGa Desk is the staff-facing support desk **and field-service platform** (analysts work at `/desk/`). | desk/index.php, desk/includes/loader.php, desk/config.php, desk/includes/controllers/actions.php, desk/includes/controllers/data.php, desk/includes/controllers/modals.php, desk/includes/classes/class.app.php, desk/includes/classes/class.ticket.php, desk/api/index.php, desk/api/resources/tickets.php, crons/tickets.php |
-| [Email-to-Ticket Intake (crons/tickets.php)](features/email-to-ticket-intake.md) | TOGa Desk ingests support email into tickets through a cron-driven IMAP poller (`crons/tickets.php`) plus a postfix pipe variant (`crons/pipe.php`). | crons/tickets.php, crons/tickets_prod.php, crons/pipe.php, desk/includes/classes/class.ticket.php |
+| [Email-to-Ticket Intake (crons/tickets.php)](features/email-to-ticket-intake.md) | TOGa Desk ingests support email into tickets through a cron-driven IMAP poller (`crons/tickets.php`) plus a postfix pipe variant (`crons/pipe.php`). | crons/tickets.php, crons/tickets_prod.php, crons/pipe.php, desk/includes/classes/class.ticket.php, vendor/classes/class.imap.php |
 | [Field-Service Dispatch (central / repair orders)](features/field-service-dispatch.md) | The **central** subsystem is TOGa Desk's field-service dispatch domain: repair-order lifecycle, technician scheduling, onsite vs depot service, parts, and shipm | desk/includes/controllers/actions/central/, desk/includes/classes/class.repair.php, desk/includes/classes/class.repairhistory.php, desk/_/browser/datatable/central.php, desk/template/pages/central.php, desk/template/pages/central/view.php, desk/template/modals/central/addTracking.php, library/app/model/togadesk/repairorder.php, library/app/model/togadesk/repairordertracking.php, library/app/api/carrier/ups.php |
 | [Managed Service Order Create Flow (New MSO modal → tickets/add)](features/managed-service-order-create.md) | The **Managed Service Order (MSO) create flow** is how a TOGa Desk user manually creates a managed service order: pick an End User (or a Client Location), choos | desk/includes/controllers/actions/tickets/add.php, desk/template/modals/tickets/addNew.php, desk/template/pages/managed.php, desk/template/pages/getinfo.php, desk/template/footer.php, library/app/model/togadesk/repairorder.php |
 | [Ticket Email Notifications (notifications table)](features/notifications.md) | Which TOGa Desk emails fire for a given client is driven **entirely by data**, not code: the `TOGaDeskSupport.notifications` table holds one row per `(clientid, | desk/includes/classes/class.notification.php, crons/tickets.php, crons/tickets_prod.php |
 | [REST API (RPC-over-POST) & API-Key Auth](features/rest-api.md) | TOGa Desk exposes a programmatic API at `desk/api/`. | desk/api/index.php, desk/api/resources/tickets.php, desk/api/resources/assets.php, desk/api/resources/authenticate.php, desk/includes/classes/class.apikey.php, desk/includes/functions.php |
 | [SMB Contract Editing & the clientMspId Corruption Trap](features/smb-contract-editing.md) | The SMB contracts page (`/desk/?route=toga/smbcontracts&togaClientId=<id>`) edits `TOGA_*.SMBContracts` rows via a modal. | desk/template/modals/toga/smbcontracts/smbContract.php, desk/includes/controllers/modals/toga/smbcontracts/smbContract.php, desk/includes/controllers/actions/toga/smbcontracts/smbContract.php, desk/includes/controllers/actions/toga/smbcontracts/edit.php |
 | [Ticket Lifecycle (class.ticket.php)](features/ticket-lifecycle.md) | All TOGa Desk ticket creation and reply handling funnels through `Ticket` in `desk/includes/classes/class.ticket.php`. | desk/includes/classes/class.ticket.php, desk/includes/controllers/actions.php, desk/includes/controllers/actions/tickets/addReply.php, desk/api/resources/tickets.php, desk/api/resources/ticket_replies.php, crons/tickets.php, crons/pipe.php, desk/includes/controllers/actions/tickets/merge.php |
+| [Reverting a TOGa Desk _production Deploy (revert-forward)](workflows/production-revert-forward.md) | How to cleanly and verifiably roll back a single ticket's changes from the togadesk `_production` branch. |  |
 | [Standalone PHP Test Script Bootstrap (TOGa Desk)](workflows/standalone-test-scripts.md) | How to write a standalone CLI PHP script that bootstraps the TOGa Desk framework for read-only testing of desk classes (e.g. |  |

package/knowledge/1.0/apps/togadesk/features/email-to-ticket-intake.md

@@ -6,13 +6,14 @@ project: TOGa Desk
 client: shared
 type: feature
 status: active
-updated: 2026-07-09
+updated: 2026-07-27
 owners: ["jcardinal", "dfranks", "mhammontree"]
 files:
   - crons/tickets.php
   - crons/tickets_prod.php
   - crons/pipe.php
   - desk/includes/classes/class.ticket.php
+  - vendor/classes/class.imap.php
 related:
   - 1.0/apps/togadesk/architecture.md
   - 1.0/apps/togadesk/features/ticket-lifecycle.md
@@ -84,6 +85,17 @@ config framework**: noise filtering is ad-hoc inline guards in the crons (the ha
   (`E_ALL` + `App_Error::handleError`), so an intake cron could **halt**. Hardened to
   `return $matches[0] ?? '';` (TRUE-79975) — important because `isSuppressedNoiseEmail` routes
   nullable/malformed sender input through `extractEmail`, putting this latent bug on the hot path.
+- **`class.imap.php` duplicate trap — the OPPOSITE direction from `class.ticket.php`.** Two
+  copies of `class.imap.php` exist with different contents: root-level
+  `vendor/classes/class.imap.php` and `desk/vendor/classes/class.imap.php`. For the
+  email-intake path the **root-level `vendor/classes/class.imap.php` is the LIVE file** — the
+  one the intake cron uses and the one PR edits/reverts must target (confirmed: TRUE-80116's
+  attachment MIME-walker rewrite, and its revert, both touched `vendor/classes/class.imap.php`;
+  the `desk/vendor/...` copy has a different blob and was never touched). This is the reverse of
+  the `class.ticket.php` rule (where `desk/includes/classes/` is live and the repo-root copy is
+  dead). Verifying the wrong copy gives a false "byte-identical across commits" result because
+  the untouched copy trivially matches. Prior guidance naming `desk/vendor/classes/class.imap.php`
+  as live is wrong for intake.
 - Attachments are deleted locally immediately after the S3 upload with **no retry** if S3 fails.
 - **`adminid` clobber on reply routing:** after `emailToTicket()` sets `$data['adminid']` from
   the FROM address (~line 1407), an asset lookup (~line 1437-1442) overwrites it with the
@@ -93,6 +105,9 @@ config framework**: noise filtering is ad-hoc inline guards in the crons (the ha
   classification. See the ticket-lifecycle doc.
 
 ## Change history
+- 2026-07-27 — corrected the live IMAP-class location: root-level `vendor/classes/class.imap.php`
+  is the file the intake cron uses (NOT `desk/vendor/classes/class.imap.php`), the opposite of the
+  `class.ticket.php` duplicate rule; added it to `files:` (dfranks)
 - 2026-07-09 — added `Ticket::isSuppressedNoiseEmail()` noise suppression (no-reply sender + "Staples PO"
   subject) wired into both feeders before ticket creation; hardened `extractEmail()` no-match to
   `''`; documented the `tickets_defaultdepartment` → "Support Desk" catch-all fall-through

package/knowledge/1.0/apps/togadesk/workflows/production-revert-forward.md

@@ -0,0 +1,67 @@
+---
+title: Reverting a TOGa Desk _production Deploy (revert-forward)
+framework: "1.0"
+repo: togadesk
+project: TOGa Desk
+client: shared
+type: workflow
+status: active
+updated: 2026-07-27
+owners: ["dfranks"]
+files: []
+related:
+  - 1.0/apps/togadesk/architecture.md
+  - 1.0/apps/togadesk/features/email-to-ticket-intake.md
+---
+
+## Summary
+How to cleanly and verifiably roll back a single ticket's changes from the togadesk
+`_production` branch. Deploys land on `_production` as **two-parent merge commits**, so a
+rollback is a `git revert -m 1` of the merge — and when later tickets have since touched the
+same file, the correct rollback is a per-hunk revert (not a whole-file restore), verified with
+`git patch-id`.
+
+## The deploy model
+Changes reach `_production` as merge commits in one of two shapes:
+- PR merge commit — `Merge pull request #NNN from agilantsolutions/TRUE-XXXX`
+- Automated merge — `Merged from TRUE-XXXX to _production (automated)`
+
+Both have two parents: parent 1 is the prior `_production` tip, parent 2 is the ticket branch.
+
+## Steps
+1. Identify the merge commit SHA for the ticket to roll back (`git log --merges` /
+   `--grep=TRUE-XXXX`).
+2. Revert it keeping the `_production` mainline:
+   ```
+   git revert -m 1 <merge-sha>
+   ```
+   `-m 1` keeps first parent (`_production`) and undoes the branch's changes. Git reverses only
+   that ticket's hunks and auto-merges around any commits that landed later.
+3. **Do not** do a whole-file restore (e.g. `git checkout <old-sha> -- path`) when a later
+   ticket has since modified the same file — that would also wipe the later ticket's work.
+
+## Verifying the revert is exact
+- **File untouched by any later ticket:** whole-file blob/byte equality vs. the pre-ticket
+  version is a valid check.
+- **File changed by later tickets:** blob equality is meaningless (line offsets shifted). Prove
+  the revert is the precise inverse of the original change with `git patch-id`:
+  ```
+  # inverse of the original merge's diff for the file
+  git show <merge-sha> -- <file> | ...invert... | git patch-id --stable
+  # our revert's diff for the file
+  git show <revert-sha> -- <file> | git patch-id --stable
+  ```
+  Equal patch-ids prove the revert change is the exact inverse of the original regardless of
+  line-offset shifts from intervening commits.
+
+## Gotchas
+- Confirm you are targeting the **live** copy of any duplicated file before verifying — e.g.
+  the email-intake IMAP class is root-level `vendor/classes/class.imap.php`, while the live
+  ticket class is `desk/includes/classes/class.ticket.php` (opposite duplicate directions). A
+  verification against the wrong (untouched) duplicate falsely reports "identical". See the
+  email-to-ticket-intake feature doc.
+- `_production` is the deploy target for togadesk (not `_main`).
+
+## Change history
+- 2026-07-27 — documented the revert-forward rollback + `git patch-id` precision check for the
+  togadesk merge-commit deploy model (dfranks)

package/knowledge/INDEX.md

@@ -7,7 +7,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **library** (Library) _(framework core)_ — 14 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 15 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
-- **togadesk** (TOGa Desk) — 9 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
+- **togadesk** (TOGa Desk) — 10 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 6 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)
 - **webhook** (Webhook) — 1 doc(s) → [1.0/apps/webhook/INDEX.md](1.0/apps/webhook/INDEX.md)
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)

package/knowledge/sessions/2026-07-27-true-79191-fulfill-ship-mhammontree.md

@@ -0,0 +1,74 @@
+---
+type: session
+slug: true-79191-fulfill-ship
+title: TRUE-79191 Fulfill & Ship — package Units of Measure full-stack (shipped, verified) + local-env fixes
+author: mhammontree
+repos: [dbchanges2, _underscore, api2, toga2-supply]
+framework: "2.0"
+client: shared
+status: active
+created: 2026-07-27
+updated: 2026-07-27
+---
+
+# Session: true-79191-fulfill-ship
+**Date:** 2026-07-27
+**Project/Repo:** toga2-supply (2.0) + _underscore / api2 / dbchanges2
+**Task:** Implement the package Units-of-Measure feature full-stack (dbchanges2 → _underscore models → api2 metadata → toga2-supply UI), verify save/retrieve locally, and prep deployment.
+
+---
+
+## What WORKED
+<!-- All verified this session -->
+- **dbchanges2 UoM migrations (4 files, committed d52f811 / 3d18971 / ceeb95d), applied + verified idempotent across all 11 local client DBs + Core_2:**
+  - `Client/2026-07-22a - MeasureUomColumns.sql` — `Measures.measureType ENUM('LENGTH','WEIGHT')` + `conversionFactorToBase DECIMAL(18,9)`; idempotent seed of **Inch** (LENGTH, factor 1) + **Pound** (WEIGHT, factor 1) via fixed v4-literal uuids + `NOT EXISTS` on slug.
+  - `Client/2026-07-22b - TrackingNumberMeasureIds.sql` — `lengthMeasureId` (governs length/width/height) + `weightMeasureId`; backfill existing rows → Inch/Pound (9605 rows on Growrk); then **hard FK constraints** (order: cols → backfill → FK). `ORDER BY id ASC` on backfill subqueries (defensive vs junk `slug='Text'` rows that exist in Compass/CompassCanada).
+  - `Core/2026-07-22a - MeasureUomRecordFields.sql` — RecordFields **2436** lengthMeasureId + **2437** weightMeasureId on tracking-numbers (MATCH/NULL, like shippingMethodId), **2438** measureType on measures (STRING, like signatureType).
+  - `Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql` — write grants for the 2 FK fields (mirror **shippingMethodId**) + **read** grant for `measures.measureType` (mirror sibling **slug**).
+- **_underscore models (committed 77fae34c), linted + php-reviewer clean:** `Measure.php` (+`measureType` FIELD_CHAR, +`conversionFactorToBase` FIELD_DECIMAL); `TrackingNumber.php` (+`lengthMeasureId`/`weightMeasureId` `[FIELD_FOREIGNKEY, FIELDOPT_FOREIGNKEY_MODEL => '\_Model_Client_Measure']`).
+- **api2 — NO code change needed** (metadata-driven; confirmed zero refs to needsReturnLabel/signatureType). Fields exposed purely via Core RecordFields + Client ACL.
+- **toga2-supply frontend (commit e91f7029d, 10 files, `tsc --noEmit` clean):** two RHF selects fed by `GET /v2/measures` split client-side by `measureType`; FK write as **nested relation `{uuid}`** (`lengthMeasure`/`weightMeasure`, mirrors shippingCarrier — NOT scalar id); read field-selectors request `lengthMeasure`/`weightMeasure`; default Inch/Pound; Pending Shipments dimension unit from length symbol.
+- **End-to-end save/retrieve VERIFIED in DB:** new tracking number **9676** (SO 7221433 / NetSuite, created 2026-07-27 12:06) has `lengthMeasureId=1` (inch) / `weightMeasureId=2` (pound) — populated by the **frontend create payload** (proves real persistence: column defaults NULL, and the 07-22 backfill predates this row).
+- **Local-env fixes** (see failures section for why these were NOT our code): `pcre.jit=0` in php.ini; `Items.isFulfillable` column added to all 11 local client DBs.
+- Deployment doc `C:\WWW\TRUE-79191_deployment_order.md` updated with all 4 UoM migrations + notes.
+
+## What did NOT work — DO NOT RETRY THESE
+- **First `22c` mirrored `needsReturnLabel` for the measure-field WRITE grants** → on `Client_True` it granted **nothing** (needsReturnLabel's own grants never propagated to every client). Writing lengthMeasureId/weightMeasureId there would return **EV-9**. FIX: mirror **`shippingMethodId`** (stable, universal, MATCH FK, same form) — it correctly copies each client's own writer roles (Growrk=1, Compass=1,3,4).
+- **Skipped granting `measures.measureType`** (assumed read-only fields need no ACL) → **WRONG.** The V2 engine builds each GET's **output** field list from `AclFieldPermissions` (`getAclFieldPermissions` + `foreach ($aclFieldPermissions as $field)` output loops in `V2.php`), so a field with no grant row for the caller's role is **silently omitted**. `GET /v2/measures` returned rows without `measureType` → the frontend LENGTH/WEIGHT split matched nothing → **both unit dropdowns rendered empty**. FIX: grant `measureType` read by mirroring sibling `slug` per-client (in `22c`).
+- **`sales-orders` 500 was NOT our UoM code** — two stacked local-env issues: (a) `preg_split(): Allocation of JIT memory failed` at `Sentry\init()` bootstrap (PCRE JIT can't allocate executable memory on this Win Enterprise machine); the framework escalates the warning to a fatal, 500-ing **every** request → FIX `pcre.jit=0` + restart Apache. Then (b) DB error **1054 Unknown column 'isFulfillable'** — the prod sync brought the updated `_Model_Client_Item` but not the `2026-07-17` migration → FIX add the column locally.
+- **Do NOT re-run `Client/2026-07-22b` after go-live** — the backfill is one-time; a re-run coerces later legitimately-NULL rows to Inch/Pound (column + FK adds are guarded, the backfill is not re-run-safe).
+- `FIELD_LIST` for measureType — rejected; `FIELD_CHAR` is correct (FIELD_LIST is reserved for fields with explicit class constants; signatureType precedent).
+
+## Not tried yet (candidates for next session)
+- **Deploy** TRUE-79191 (deployment order doc is ready) — the actual go-live.
+- Seed **cm/kg** into a client (metric, per-client opt-in) to exercise multi-option dropdown — offered, not done (Growrk currently US-only, so saved value == default value visually).
+- **Full local DB migration catch-up / reset from beta** — drift scan found **16 genuine missing columns** in unrelated tables (TransferOrders, Cases, Questions, TicketSlas, Persona/Language/User RecordFieldSettings, Integrations, Bills, SectionRecordFields) — none in the fulfill/ship path. (5 more "missing" were FIELD_STORAGE false positives: labelPdfFile, imageFile, invoicePdfFile, Files.data, fileData.)
+- Make the **weight symbol on Pending Shipments cards dynamic** (currently static `"lbs."`; TODO in ShipmentsCardTableForm; weightMeasure.symbol already fetched).
+- Register `isFulfillable` RecordField/interceptors locally (skipped — id-2434 collision).
+
+## Current file state
+| File | Status | Notes |
+|------|--------|-------|
+| dbchanges2 Client 2026-07-22a/b/c, Core 2026-07-22a | committed (d52f811/3d18971/ceeb95d), applied to all 11 local clients + Core_2 | UoM schema + seed + backfill + FK + RecordFields + ACL |
+| _underscore Model/Client/Measure.php, TrackingNumber.php | committed (77fae34c) | UoM model fields; survived prod merges |
+| toga2-supply (10 src files) | committed (e91f7029d) | UoM UI; .env/.env.development/package-lock intentionally uncommitted |
+| api2 | no changes | metadata-driven; only untracked local Config/dev-*.ini |
+| C:\WWW\TRUE-79191_deployment_order.md | updated (external) | UoM migrations + notes added |
+| Local: php.ini pcre.jit=0; all client Items.isFulfillable column | applied (local env only) | NOT repo changes; beta/prod unaffected |
+
+## Decisions made
+- **Columns `lengthMeasureId` + `weightMeasureId`** (not dimension/volume); **volume dropped entirely** (Jeff). One length unit governs length/width/height.
+- **Reuse Measures + `measureType` enum, zero new tables**; base units Inch/Pound; `conversionFactorToBase` convention `value_in_base = value × factor`. (Two-table alternative rejected by Jeff.)
+- **Hard FK constraints** (Jeff "+ FKs"; values fully controlled via seed+backfill; matches `UnitTypes.sql` precedent) — rejected logical-only (returnAddressId precedent).
+- **Mirror `shippingMethodId`** for write grants (universal/stable), **mirror `slug`** for measureType read grant — rejected needsReturnLabel (incomplete propagation).
+- **`pcre.jit=0` is a local-only env fix**, not code — beta/prod PHP permits JIT, so nothing to ship.
+- **isFulfillable: add column only locally**, skip RecordField (its migration hardcodes `id=2434`, colliding with returnAddressId `2026-07-10a` also 2434 — flag to that feature's owner).
+
+## Blockers
+None blocking. Ready to deploy. **Before running `Core/2026-07-22a` in production, verify `SELECT MAX(id) FROM Core.RecordFields = 2435`** — the migration hardcodes ids 2436-2438; if the sequence advanced, bump them.
+
+## Exact next step
+> Deploy TRUE-79191 per `C:\WWW\TRUE-79191_deployment_order.md` (order: DB → backend → frontend). First confirm prod `MAX(Core.RecordFields.id) = 2435` (else bump the 2436-2438 ids in `Core/2026-07-22a`), run `composer install` on api2 (FPDF) + apply production carrier config, and separately flag the unrelated `isFulfillable` migration's `id=2434` collision to its owner.
+
+---
+_Saved by /session-save on 2026-07-27_

package/package.json

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