toga-ai 1.0.310 → 1.0.311

package/knowledge/clients/prudential/INDEX.md

@@ -6,6 +6,6 @@
 | [Prudential: Dell LCH IOP transmissions (LCHRequestV2)](features/dell-lch-iop-transmissions.md) | 1.0 | Outbound order transmissions from the 1.0 worker tier to Dell's Lifecycle Hub (LCH) ITSM integration. | library/app/api/delllch.php, worker/crons/toga2/prudential/transmissions_to_dell.php, worker/crons/toga2/prudential_beta/transmissions_to_dell_india.php, worker/crons/toga2/prudential_beta/transmissions_to_dell_ireland.php, worker/crons/toga2/prudential_beta/transmissions_to_dell_usa.php |
 | [Prudential: Device information import + unit→contact linking (import_device_information.php)](features/device-information-import-and-contact-linking.md) | 1.0 | Prudential's **device-sync** cron (`worker/crons/toga2/prudential/import_device_information.php`) pulls device/asset records (from ServiceNow / the Dell CMDB fe | worker/crons/toga2/prudential/import_device_information.php, worker/crons/toga2/prudential/backfill_unit_contacts.php, dbchanges2/Client_Prudential/2026-07-07 - Contact Dedup Merge.sql |
 | [Prudential: Service Request Regional Address Validation](features/service-request-address-validation.md) | 2.0 | The `prePost` interceptor on `_Model_Prudential_ServiceRequest` validates `deliverToAddress` fields differently depending on which Prudential regional customer | _underscore/Model/Prudential/ServiceRequest.php |
-| [Prudential Order Shipped Email — transmit_ordershipped_updates_prudential.php](features/transmit-ordershipped-email.md) | 1.0 | Cron script that transmits "Order Shipped" updates to ServiceNow (RITM) and sends a shipped notification email to the end user. | worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php, worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php, worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php, worker/crons/toga2/prudential_beta/generate_sales_and_purchase_orders_from_service_requests.php |
+| [Prudential Order Shipped Email — transmit_ordershipped_updates_prudential.php](features/transmit-ordershipped-email.md) | 1.0 | Cron script that transmits "Order Shipped" updates to ServiceNow (RITM) and sends a shipped notification email to the end user. | worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php, worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php, worker/crons/toga2/prudential/transmit_rejected_cancelled_updates_prudential.php, worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php, worker/crons/toga2/prudential_beta/generate_sales_and_purchase_orders_from_service_requests.php, worker/crons/notifications/reports/prudential_exception_report.php |
 | [Prudential Financial](profile.md) | 2.0 | Prudential is a TOGA client whose device-fulfillment flow is driven by **Dell** via the Dell API (`Client_Prudential.Apis.id = 2`). |  |
 | [Prudential: Dell ASN failed POST backfill replay](workflows/dell-asn-backfill-replay.md) | 2.0 | When Dell ASN POSTs fail in bulk (e.g. |  |

package/knowledge/clients/prudential/features/transmit-ordershipped-email.md

@@ -6,13 +6,15 @@ project: Worker
 client: prudential
 type: client-feature
 status: active
-updated: 2026-07-06
+updated: 2026-07-10
 owners: ["rgirish"]
 files:
   - worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php
   - worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php
+  - worker/crons/toga2/prudential/transmit_rejected_cancelled_updates_prudential.php
   - worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php
   - worker/crons/toga2/prudential_beta/generate_sales_and_purchase_orders_from_service_requests.php
+  - worker/crons/notifications/reports/prudential_exception_report.php
 related:
   - ../profile.md
 ---
@@ -47,11 +49,37 @@ Iterates the same POs collected in Phase 1. For each:
 - `Client_Prudential.PurchaseOrders.c_dtEmailSentOrderShipped` — stamped after email send
 - Both fields are checked by `prudential_exception_report.php` to detect discrepancies
 
+**⚠ `c_dtTransmittedOrderClosedUpdateToPrudential` is an OVERLOADED column (discovered 2026-07-10).**
+It is written by TWO different crons for THREE distinct terminal outcomes:
+- **Delivered / Closed-Complete** — stamped by `transmit_closecomplete_updates_prudential.php`,
+  gated on an ASN with a `DELIVERED` tracking number, and **pairs with a customer email**
+  (`c_dtEmailSentOrderClosed`). *Only this path owes an email.*
+- **Rejected / Cancelled** — stamped by `transmit_rejected_cancelled_updates_prudential.php`,
+  with **no ASN join**; it only pushes a ServiceNow "rejected"/"cancelled" RITM update and
+  **sends no customer email**.
+
+So a no-ASN Rejected/Cancelled PO shows a "delivered" transmit stamp with `c_dtEmailSentOrderClosed`
+NULL forever — that is correct, not a failure. Any query keyed on this column alone will
+conflate the two. Example: REQ4448998 (PO 26544) was a Rejected order with no ASN/tracking and
+was a false positive in the "Order Delivered Email Not Sent" report.
+
 ## Exception report link
 `worker/crons/notifications/reports/prudential_exception_report.php` flags any PO where
 `c_dtTransmittedOrderShippedUpdateToPrudential IS NOT NULL` AND `c_dtEmailSentOrderShipped IS NULL`
 as "Order Shipped Email Not Sent". This appears daily in the Prudential REQ Processing Report email.
 
+**Order-Delivered discrepancy query — DELIVERED gate required (fixed 2026-07-10, ~line 463-474).**
+The Order-Delivered discrepancy query originally filtered only on
+`c_dtTransmittedOrderClosedUpdateToPrudential IS NOT NULL AND c_dtEmailSentOrderClosed IS NULL`
+with no shipment/stage filter. Because that column is overloaded (see Data model), every
+Rejected/Cancelled Dell PO was flagged as an "Order Delivered Email Not Sent" failure even though
+it never owed a delivery email. Fix: add
+`AND EXISTS (AdvanceShippingNotices → ASNItems → ASNItemUnits → ASNItemUnits_TrackingNumbers →
+TrackingNumbers WHERE purchaseOrderId = PurchaseOrders.id AND TrackingNumbers.status = 'DELIVERED')`
+— this mirrors the closecomplete cron's own Phase-1 email precondition, so the report only flags
+orders that genuinely qualified for a delivery email. Over 2026-07-01..07-09 this dropped 6 false
+positives (25 → 19 flagged) while retaining all 19 genuine discrepancies.
+
 ## Sibling scripts sharing this pattern
 The same two-phase (transmit-then-email) shape and the same PDF-fetch fragility exist in three
 sibling crons, all fixed the same way this session (2026-07-06):
@@ -65,6 +93,21 @@ sibling crons, all fixed the same way this session (2026-07-06):
 
 ## Gotchas / known issues
 
+**ROOT CAUSE (third regression) — `App_Database::escapeString()` does not exist → fatal on the 404 auto-create path (fixed 2026-07-10):**
+`createAssetAndRetryPut()` in **both** `transmit_ordershipped` and `transmit_closecomplete`
+(~line 158) called `App_Database::escapeString($serialNumber)`. **That method does not exist** on
+`App_Database` — only `sqlEscape`, `sqlProtect`, and `mysqlRealEscapeString` do. Under the 1.0
+framework's `error_reporting(E_ALL)`, calling a non-existent static method is a **fatal `Error`
+that kills the cron mid-run**. It fires whenever an asset PUT to ServiceNow returns 404
+(`isAssetNotFoundError`) — routine for Breakfix/Reclaim/Refresh returned/replacement assets not yet
+in the Prudential CMDB. The fatal occurs in Phase 1 **after** the transmit flag is stamped but
+**before** the email phase, so the email is permanently stranded (email flag left NULL). This was
+the specific unaddressed trigger of the month-long email-stranding — distinct from, but riding on
+top of, the two-phase design flaw below. **Fix: `escapeString` → `sqlEscape` in both files**
+(`sqlEscape` is already used correctly elsewhere in the same files, e.g. ordershipped line 1386).
+This was flagged as a "latent error" in the 2026-07-06 pre-existing-issues note; it turned out to
+be the live trigger.
+
 **ROOT CAUSE — `file_get_contents` in a 1.0 cron THROWS, it does not return false (discovered 2026-07-06):**
 The 1.0 framework bootstrap sets `error_reporting(E_ALL)` and `App_Error::handleError`
 (`library/app/error.php` ~line 348) converts **every** PHP warning into an `ErrorException`.
@@ -110,8 +153,8 @@ URL was still live in 3 of the sibling files and was corrected this session.
 **Pre-existing issues surfaced this session (NOT fixed — awareness only):**
 - SQL-injection risk: unescaped `$reqNumber` concatenated into a `LIKE '%...%'` query in the
   Phase-2 body of both `transmit_ordershipped` and `transmit_closecomplete`.
-- `transmit_closecomplete` calls `App_Database::escapeString()` (~line 158) which does not exist
-  on `App_Database` (only `sqlEscape` does) — latent error in the `createAssetAndRetryPut` path.
+- (RESOLVED 2026-07-10) `App_Database::escapeString()` at ~line 158 in **both** crons — see the
+  ROOT CAUSE gotcha above; this "latent" error was the actual fatal trigger, now fixed to `sqlEscape`.
 - Separate inbound issue: Dell SR re-POST hitting `ServiceRequests.number` UNIQUE constraint →
   API 400 "Duplicate entry SR129013" (REQ4444748). Not part of the email fix.
 
@@ -132,5 +175,20 @@ stamp (crash hits the next iteration). With multiple New-type POs, a crash on PO
 all subsequent POs in the same run.
 
 ## Change history
+- 2026-07-10 — Third regression of the "Order Shipped / Order Delivered Email Not Sent" symptom.
+  True trigger: `createAssetAndRetryPut()` called the nonexistent `App_Database::escapeString()`
+  (~line 158 in `transmit_ordershipped` + `transmit_closecomplete`) — a fatal `Error` under E_ALL
+  that fired on the ServiceNow 404 asset auto-create path (routine for Breakfix/Reclaim/Refresh),
+  killing Phase 1 after the transmit stamp but before the email. Fixed `escapeString` -> `sqlEscape`
+  in both files (verified by 3 adversarial subagents; php -l clean). Recovered by nulling the
+  transmit flags for 9 stranded shipped POs + 1 closed PO (re-processing is idempotent) — the 9
+  owed shipped emails were confirmed sent 2026-07-10 09:34-09:35.
+  Also: discovered `c_dtTransmittedOrderClosedUpdateToPrudential` is overloaded across
+  Delivered vs Rejected/Cancelled (only Delivered owes an email), and fixed the
+  `prudential_exception_report.php` Order-Delivered discrepancy query to require an EXISTS on a
+  DELIVERED tracking number (drops Rejected/Cancelled false positives; REQ4448998/PO 26544 was one).
+  The structural two-phase stamp-before-email flaw remains **open** — candidate durable fix: stamp
+  the email flag only after a successful send and/or wrap each PO's email phase in try/catch. Not
+  done this session (scoped to the specific trigger) (rgirish)
 - 2026-07-06 — Found the real root cause: `file_get_contents` throws (E_ALL→ErrorException) so the `!== false` guards (incl. the 2026-06-18 one) were never effective. Added `safeFetchPdf()` (try/catch ErrorException → false) + independent per-PDF guards; email now always sends even if a PDF fails. Extended the same fix to `transmit_closecomplete` and both `generate_sales_and_purchase_orders_from_service_requests` scripts, and finished the stale Mac PDF URL fix in the 3 files the 2026-06-18 change missed. Documented the permanent two-phase stranding flaw and the date-bounded-recovery requirement; scope kept to fix-forward (no auto self-heal) by developer decision (rgirish)
 - 2026-06-18 — Fixed 403 crash: corrected Mac PDF URL (`_15.6_v4` → `PrudentialMacSetupGuide.pdf`) and added a `!== false` guard on all S3 fetches in New branch. NOTE (2026-07-06): this guard was ineffective — the exception is thrown inside `file_get_contents`, not returned (rgirish)

package/package.json

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