toga-ai 1.0.297 → 1.0.299

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

@@ -8,5 +8,5 @@
 | [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/api/resources/tickets.php, crons/tickets.php, desk/includes/controllers/actions/tickets/merge.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 |
 | [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,8 +6,8 @@ project: TOGa Desk
 client: shared
 type: feature
 status: active
-updated: 2026-06-15
-owners: ["jcardinal"]
+updated: 2026-07-09
+owners: ["jcardinal", "dfranks"]
 files:
   - crons/tickets.php
   - crons/tickets_prod.php
@@ -61,6 +61,14 @@ Writes `tickets`, `tickets_replies`, attachment `files`; reads config from the `
 - **Auto-reply filters** are partly hardcoded (e.g. ignore `TechHub@compass-usa.com`
   "Automatic reply:" messages).
 - 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
+  replying user's asset's assigned admin. On a matched-ticket reply this makes a user's email
+  look like a staff reply in `addReply()` (`isAdminReply=true`), so `Awaiting User` etc. never
+  transition. The asset-derived adminid is for NEW-ticket auto-assign in `add()`, not reply
+  classification. See the ticket-lifecycle doc.
 
 ## Change history
+- 2026-07-09 — documented the `emailToTicket()` adminid-overwrite reply misclassification
+  (TRUE-80114 planning investigation) (dfranks)
 - 2026-06-15 — documented from a source read of `crons/tickets*.php` and `emailToTicket()` (jcardinal)

package/knowledge/1.0/apps/togadesk/features/ticket-lifecycle.md

@@ -6,13 +6,16 @@ project: TOGa Desk
 client: shared
 type: feature
 status: active
-updated: 2026-06-12
-owners: ["mhammontree"]
+updated: 2026-07-09
+owners: ["mhammontree", "dfranks"]
 files:
   - 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
 related:
   - 1.0/apps/togadesk/features/smb-contract-editing.md
@@ -40,6 +43,26 @@ Creation paths — all funnel through `Ticket::add($data)`:
 - Ticket merge (`actions/tickets/merge.php`) inserts a master ticket directly — it copies
   fields from the child, including `customerid` (since June 2026).
 
+### Reply entry points (FOUR doors — only two transition status)
+There are **four** inbound reply paths, but the status-transition switch lives ONLY inside
+`Ticket::addReply()`. Any door that does not route through `addReply()` will not change status:
+- **IMAP-poll cron** — `crons/tickets.php` → `emailToTicket()` → `addReply()`. ✅ transitions.
+- **Mail pipe** — `crons/pipe.php:113` → `emailToTicket()` (legacy 6-arg call) → `addReply()`.
+  ✅ transitions.
+- **Desk REST API** — `desk/api/resources/ticket_replies.php` `'add'` → `addReply($data)`
+  directly. ✅ transitions.
+- **togaview customer portal** — the portal reply form (`action="/ticket"` + `newReplyBtn`,
+  from the generic `common/togaview/ticket.php` and client variants e.g.
+  `common/newcenturyholdingsllc/ticket.php`, `common/towfoundation/ticket.php`) POSTs to
+  `togaview/mvc/ticket/post.php` `newReplyBtn` handler (~line 388). This handler inserts the
+  reply row **directly** via `App_Model_TogaDesk_TicketReply` and **bypasses the `Ticket` class
+  entirely** — it never updates `tickets.status`, `tickets_replies.newStatus`, or
+  `tickets_history`. ❌ **no status transition.** This is the gap behind "a reply from outside
+  Desk doesn't move the ticket."
+
+The in-Desk agent reply path is `desk/includes/controllers/actions/tickets/addReply.php` →
+`Ticket::addReply($_POST)`.
+
 ## How it works
 
 ### `Ticket::deriveCustomerId(int, string): ?int` (added June 2026)
@@ -64,6 +87,11 @@ means the reply lands but the ticket status silently never changes (no history e
 re-entry). That was the On Hold SLA bug; `case 'On Hold'` (admin ⇒ stays On Hold, client ⇒
 Open) was added June 2026.
 
+- **`origin` is the reliable "reply came from outside Desk" signal.** The in-app agent reply
+  path (`addReply.php` → `addReply($_POST)`) carries **no `origin` key**, whereas
+  `emailToTicket()` sets `tickets.origin = 'EMAIL'` and togaview sets `'TOGAVIEW'` on new
+  tickets. Absence of `origin` on a reply therefore identifies an in-app agent reply; presence
+  identifies an external reply. This is the safe hook for any "external reply → status" logic.
 - Special case: an admin replying to their OWN ticket is treated as a user reply.
 - Auto-assign on first staff reply requires the role perm `allowAutoAssign` via
   profiles/profile_departments.
@@ -88,11 +116,29 @@ backfill (e.g. craftex:
   column (close time would have to come from `tickets_replies.newStatus='Closed'` or
   `tickets_history`). Implementing it is a product decision: what happens to a lapsed reply
   (attach-but-closed / new ticket / bounce)?
+- **`emailToTicket()` clobbers `adminid`, misclassifying user email replies as staff replies.**
+  After matching the sender and setting `$data['adminid']` from the FROM address (~line 1407),
+  an asset lookup (~line 1437-1442) **overwrites** `$data['adminid']` with the replying user's
+  asset's assigned admin. When the matched ticket goes to `addReply()`, the user's reply is
+  read as an admin/staff reply (`isAdminReply=true`), so states like `Awaiting User` stay put
+  instead of transitioning to `Open`. The asset-derived adminid is meant for auto-assigning
+  NEW tickets in `add()`, not for classifying replies — `adminid` serves two conflicting
+  purposes here.
+- **Cross-app DB coupling:** togadesk and togaview share the `TOGaDeskSupport` database
+  (`tickets`, `tickets_replies`, `tickets_history`, `people`), so a reply/status behavior
+  change on either side is visible to both immediately. togaview cannot load Desk's
+  `class.ticket.php`, so its writes go through the `App_Model_TogaDesk_*` models
+  (`TicketReply`, `TicketsHistory`, `Ticket`) — any shared status logic must account for that
+  the portal path never instantiates `Ticket`.
 - Legacy `togadesk/includes/class.ticket.php` has active email-reopen logic; the live
   `desk/includes` version has it commented out — email replies never set status to "Reopened"
   via `emailToTicket()`.
 
 ## Change history
+- 2026-07-09 — mapped the four reply entry points (togaview portal bypasses `addReply()` so
+  never transitions status); documented `emailToTicket()` adminid-overwrite reply
+  misclassification, the `origin`-absence agent-reply signal, and togadesk↔togaview shared-DB
+  coupling — from TRUE-80114 planning source investigation (dfranks)
 - 2026-06-12 — documented from craftex MSP portal debugging session (mhammontree)
 - 2026-06 — added `deriveCustomerId()`; added `On Hold` case to addReply() switch; merge
   copies `customerid` (mhammontree)

package/knowledge/clients/nycdoe/features/servicenow-integration.md

@@ -6,8 +6,8 @@ project: Worker
 client: nycdoe
 type: client-feature
 status: active
-updated: 2026-06-19
-owners: [mhammontree]
+updated: 2026-07-09
+owners: [mhammontree, sking]
 files:
   - worker/crons/sync/nycdoe/import_asn.php
   - worker/crons/sync/nycdoe/import_inc.php
@@ -17,6 +17,7 @@ files:
   - worker/crons/sync/nycdoe/1_send_asn_to_netsuite.php
   - worker/crons/sync/nycdoe/2_send_serials_to_netsuite.php
   - worker/crons/sync/nycdoe/3_create_installation_ticket.php
+  - worker/crons/sync/nycdoe/test_multi_po_receipt_resolution.php
   - worker/crons/sync/nycdoe/send_ticket_updates.php
   - worker/crons/sync/nycdoe/send_request_item_updates.php
   - worker/crons/sync/nycdoe/send_nycdoe_proof_of_delivery.php
@@ -34,6 +35,7 @@ files:
   - library/app/asnprocessor/lexmark.php
   - library/app/asnprocessor/acer.php
   - library/app/edi.php
+  - library/app/netsuite.php
 related:
   - ../profile.md
   - hold-status-sync.md
@@ -131,12 +133,27 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
   `qtyOrder` is immutable** — there is no update path to a sent SO line; growth must be a
   new item row → new SO line.
 - **Stage 4:** reconciles the NetSuite **PO** (`netSuiteInternalPurchaseOrderId` — not the
-  SO id) and sends serial inventory assignments.
+  SO id) and sends serial inventory assignments. It is already multi-PO aware
+  (`listPurchaseOrdersCreatedFromSalesOrder`, groups items by PO, stamps each item's
+  `netSuiteInternalPurchaseOrderId`) **but only stamps items where the PO is NULL and never
+  re-stamps** — so an item stamped to PO-A but later *received* on PO-B is never corrected.
+  **TOGA does NOT create NetSuite POs anywhere in the DOE flow.** Stage 3 creates only the SO
+  (and, when needed, a special-order inventory Item); POs are generated inside NetSuite by
+  procurement/special-order. A single SO can therefore be fulfilled across **multiple POs**
+  (back-orders, multi-vendor, re-cut lines) — this is a legitimate NetSuite outcome, so the
+  durable fix lives downstream (resolve receipts SO-wide), not in preventing PO splits.
 - **Stage 5:** for units `WHERE togadeskRepairOrderId IS NULL`, reads serials from NetSuite
   item receipts (so TOGa Desk RO serials are **driven by NetSuite**, not the ASN unit),
   creates/reuses TOGa Desk manufacturers/models/assets/serial-numbers/MSO and creates **a
   new repair_orders row unconditionally per loop iteration** — one RO per Unit (a 50-cable
   line = 1 unit = 1 RO). Existing-serial lookup is scoped **per item row** (`$asnItemId`).
+  Item receipts are now resolved **Sales-Order-wide** via
+  `App_NetSuite::listItemReceiptsCreatedFromSalesOrder($soId)` (fans out across ALL POs from
+  `listPurchaseOrdersCreatedFromSalesOrder`, dedupes receipts by `internalId`), cached once
+  per ASN, with `getItemReceipt` cached per receipt id. The inner item query also requires
+  `netSuiteInternalSalesOrderId IS NOT NULL` so a null-SO first row cannot poison the per-ASN
+  receipt cache. Self-healing: units previously stuck under an unstamped PO clear on
+  subsequent 5-min cron runs.
 - **"#/N received" UI** (`togadesk/desk/template/pages/managedserviceorders/view.php`):
   denominator = `SUM(qtyOrder)` per part (committed + unsent); numerator = Units with
   `togadeskRepairOrderId IS NOT NULL`.
@@ -218,6 +235,36 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
 - **Stage 6 is not currently running** (`4_` paused with `active: 0`, `5_` unscheduled).
 - TRUE-77354: Stage 5 lookups changed `LIKE` → `=` to stop `_`/`%` wildcard matches in
   serials.
+- **Multi-PO-per-SO silently drops install tickets (FIXED 2026-07-09).** Stage 5 used to
+  fetch item receipts only for the single stamped `netSuiteInternalPurchaseOrderId`. When a
+  NetSuite SO is fulfilled across more than one PO, units received under a PO *other* than the
+  stamped one never got a TogaDesk repair order, and the every-5-min cron silently re-queried
+  the wrong PO forever. No error was raised — the symptom was serials never syncing. Fixed by
+  resolving receipts SO-wide (see Stage 5). Before, no `App_NetSuite` method listed receipts
+  by SO — only by PO (`listItemReceiptsCreateFromPurchaseOrder`) or location
+  (`listAllItemReceiptsForLocation`); the new `listItemReceiptsCreatedFromSalesOrder`
+  (`library/app/netsuite.php`, after `listItemReceiptsCreateFromPurchaseOrder`) fills that gap.
+  Concrete case: customer PO `S202643596` (ASN 26339, SO internalId 6971858) split across PO
+  164785 (internalId 6971859 → `38S0500` synced, 15 ROs) and PO 165751 (`50M7280` + `A3L980`
+  NOT synced). PRs: library#831 (merge first) then worker#1670.
+
+## Debugging & DB topology (DOE 1.0 sync)
+
+Reference for future DOE investigations — the 1.0 worker cannot run on a dev/Windows box;
+use the toga DB MCP + `Logs.API` instead of running prod code locally.
+
+- **`db_core` alias → legacy (V1) environment, schema `Core`** — holds the FLAT tables
+  `AdvanceShippingNotices` / `AdvanceShippingNoticeItems` / `AdvanceShippingNoticeUnits`
+  (columns incl. `togadeskRepairOrderId`, `serialNumber`, `netSuiteInternalSalesOrderId`,
+  `netSuiteInternalPurchaseOrderId`, `customerPurchaseOrder`). The 1.0 cron reads **legacy/Core**.
+- **Do NOT confuse with prod (V2) `Client_Nycdoe`** — a DIFFERENT, normalized schema
+  (`AdvanceShippingNoticeItemUnits` with a `unitId` FK). The 1.0 cron does not read V2.
+- **NetSuite SOAP request/response payloads** are logged in legacy `Logs.API` — filter
+  `sourceJob LIKE '%3_create_installation_ticket%'`; `requestPayload` contains the PO
+  internalId. (The multi-PO case above was verified this way: the receipt search for PO
+  6971859 returned `totalRecords=1`, only `38S0500`.)
+- **`Bridge_NetSuite`** (legacy) has `SalesOrders` / `SalesOrderItems` / `SerialNumbers` but
+  **no `PurchaseOrders` table** — POs are pulled live from the NetSuite API.
 
 ## Operating rules when changing this integration
 
@@ -231,6 +278,14 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
    of the consumer query; `php -l` every touched file.
 
 ## Change history
+- 2026-07-09 — Fixed silent install-ticket drop when a NetSuite SO is fulfilled across
+  multiple POs: Stage 5 now resolves item receipts Sales-Order-wide via new helper
+  `App_NetSuite::listItemReceiptsCreatedFromSalesOrder` (fans across all POs from the SO,
+  dedupes by internalId, cached per ASN), and its item query requires
+  `netSuiteInternalSalesOrderId IS NOT NULL`. Root cause: TOGA doesn't create DOE POs, so
+  multi-PO-per-SO is legitimate and units received on an unstamped PO were never ticketed.
+  Added multi-PO notes to Stage 4/5, a gotcha, and a DB-topology/debugging section.
+  PRs library#831 + worker#1670. (sking)
 - 2026-06-29 — Outbound status sync now keeps DOE holds authoritative (TRUE-79922). Hold
   detection moved to the SNOW native `state` field (not `u_status_task`); Assigned-force
   blocks guarded against local `HOLD_*` to stop the `state:3`↔`state:2` self-clobber; RITM

package/package.json

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