toga-ai 1.0.570 → 1.0.571

package/knowledge/clients/compass-usa/features/odp-edi-855-acknowledgement-and-overquantity-guard.md

@@ -94,6 +94,31 @@ The 850 carries the identifiers the 855 echoes back:
 full 850 → TOGa identifier map, incl. `BEG` = ODP PO number and `REF*QC` = the value to
 search on for the ODP SalesOrder.)
 
+## Rejections raise a business alert (Logs.Issue)
+A reject used to be **silent** — the PO was skipped and no human was notified. Cron `3a` now
+surfaces every over-quantity/duplicate rejection as a curated **Logs.Issue** alert by throwing
+`App_Exception_Business` (issue key **`COMPASS_OFFICE_DEPOT_PO_IMPORT_REJECTED_OVER_QUANTITY`**,
+`URGENCY_HIGH`, message listing the rejected PO numbers). The reject 855 is still built and
+acknowledged back to Office Depot first; the alert is purely additional notification. The issue
+key follows the sibling cron `1_transmit_compass_sales_orders_to_mits.php` naming convention.
+
+### ⚠ Gotcha — the throw is DEFERRED to end-of-run, never inline
+The exception is **not** thrown in the reject branch. It is deferred to the very end of the run:
+after the full `$ediFiles['Contents']` loop, after each S3 850 file is logged + deleted, and
+after `App_Framework::cronFinished()`. A single collector array
+(`$rejectedPurchaseOrderNumbers`) accumulates rejected PO numbers across all files/POs, and one
+exception is thrown at end-of-run.
+
+**Why it must be deferred:** an inline throw unwinds the loop *before* the per-file S3 delete, so
+the same 850 is re-fetched next run and a **duplicate reject 855 is re-sent to Office Depot every
+run — an "855 storm."** Deferring guarantees each 850 is deleted first, and the stable issue key
+collapses multiple rejects into one Logs.Issue.
+
+Throwing **after** `cronFinished()` is safe: the overlap guard
+(`App_Framework::exitIfProcessRunning`, a `ps -ef` process-table scan) has no dependency on
+cronFinished's `CronJobExecutions` checkout row, and on CLI an uncaught `App_Exception_Business`
+just echoes `ERROR [ref]:` and exits.
+
 ## ⚠ Open item — reject codes vs ODP's 855 companion guide
 The reject codes used (`BAK02 = RD`, `ACK01 = IR`) are the **standards-correct** X12 values.
 They have **not** yet been confirmed against Office Depot's 855 companion guide. If ODP
@@ -102,6 +127,13 @@ A legacy, abandoned sketch (`compass/edi/3_send_edi_855(reject).php`) used **non
 codes `BAK01 = A1` / `BAK02 = RE` — that path was **deliberately NOT followed**.
 
 ## Change history
+- 2026-08-13 — Rejections now raise a business alert: cron `3a` throws
+  `App_Exception_Business` (`COMPASS_OFFICE_DEPOT_PO_IMPORT_REJECTED_OVER_QUANTITY`,
+  `URGENCY_HIGH`) so every over-quantity/duplicate reject surfaces as a Logs.Issue instead of
+  being silent. The throw is **deferred to end-of-run** (after the file loop, per-file S3
+  delete, and `cronFinished()`) via a `$rejectedPurchaseOrderNumbers` collector — an inline
+  throw would skip the S3 delete and cause an "855 storm" (same 850 re-fetched, duplicate reject
+  855 re-sent every run). `php -l` clean; php-reviewer 0/0. (jcardinal)
 - 2026-08-13 — Built the over-quantity guard on the ODP 850 importer (cron 3a): ODP
   re-sending an already-processed Compass SO line under a new PO number now rejects the whole
   PO (new helper `officeDepotPurchaseOrderExceedsCompassDemand()`, "first occurrence passes",

package/package.json

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