toga-ai 1.0.568 → 1.0.569

package/knowledge/INDEX.md

@@ -5,7 +5,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 1.0 framework
 
 - **library** (Library) _(framework core)_ — 17 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
-- **worker** (Worker) — 22 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
+- **worker** (Worker) — 23 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/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) — 12 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)

package/knowledge/clients/compass-usa/INDEX.md

@@ -12,6 +12,7 @@
 | [Compass MITS PO rejection — zero line items (400 + Issue + PM alert email)](features/mits-po-zero-line-item-rejection.md) | 2.0 | MITS transmits Compass purchase orders that carry **`"purchaseOrderItems": []`** (real example: PO `50309196-1`, `mitsSalesOrder` `MR244630`). | _underscore/Model/Compass/PurchaseOrder.php, _underscore/Model/Compass/Usa/PurchaseOrder.php, _underscore/Model/Compass/Canada/PurchaseOrder.php, worker2/Worker/Client/Compass/reports/PurchaseOrderRejectionEmail.php |
 | [Compass MITS Sales-Order Transmission — Rejection Alerting (Issue/Event, not email-in-cron)](features/mits-sales-order-transmission-alerting.md) | 2.0 | When MITS **rejects** a Compass sales order transmitted by the 1.0 cron `1_transmit_compass_sales_orders_to_mits.php`, the alert is no longer an email built ins | worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, worker2/Worker/Infrastructure/Errors.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/IssueEmailAddress.php, dbchanges2/Logs/2026-08-04a - MITS rejection business recipients.sql |
 | [Compass MR/MA Order Auto-Approval & Status Gate](features/mr-ma-order-approval-and-status.md) | 2.0 | Compass **MR** and **MA** sales orders are system-generated from the MITS / Office Depot EDI pipeline (they do not originate as user-entered SA orders) and must | _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/PurchaseOrder.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php |
+| [Compass Office Depot EDI 855 Acknowledgement + Over-Quantity PO Guard](features/odp-edi-855-acknowledgement-and-overquantity-guard.md) | 1.0 | How Compass acknowledges Office Depot (ODP) inbound **EDI 850** purchase orders with an **X12 855**, and the **over-quantity guard** that rejects a duplicate PO | worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, worker/crons/toga2/compass/workflow/4_transmit_office_depot_po_acknowledgements.php, library/app/edi.php |
 | [Compass PEOPLE-File User Lifecycle (duplicate accounts, reactivation grace window, raw-SQL deactivation)](features/people-file-user-lifecycle.md) | 2.0 | The nightly **PEOPLE** file cron (`_Worker_Client_Compass_PeopleFile`, `worker2/Worker/Client/Compass/PeopleFile.php`) owns the whole `Users` row lifecycle for | worker2/Worker/Client/Compass/PeopleFile.php |
 | [Persona Model & Levy-Sector Gating (worker2 PEOPLE cron)](features/persona-model-and-levy-gating.md) | 2.0 | Compass USA catalogue visibility is driven by **personas** in `Client_Compass`. | worker2/Worker/Client/Compass/PeopleFile.php |
 | [Compass Sales-Order Line-Number Renumbering (and why it hangs off the SO hooks)](features/sales-order-line-renumbering.md) | 2.0 | Compass sales-order lines must stay numbered **1..N with no gaps** after any add, edit, or delete — downstream MITS/PO linking reads `lineNumber` as an identity | _underscore/Model/Compass/SalesOrderItem.php, _underscore/Model/Compass/SalesOrder.php |
@@ -19,7 +20,7 @@
 | [Compass Cross-Kit Bundle Corruption — Detection & Repair](workflows/cross-kit-bundle-corruption.md) | 2.0 | A frontend regression in `toga2-commerce`'s edit-order bundle submission mis-attributed bundle (kit) line items and **fees/warranties** to the **wrong kit**, pe | src/api/syncSalesOrderItemsFromLocalStorageCartToApi.ts |
 | [Compass Office Depot Duplicate PO-Line Cleanup (dual-catalog SKU)](workflows/odp-duplicate-po-line-cleanup.md) | 1.0 | The NetSuite fulfillment-sales-order importer duplicated Office Depot purchase-order lines on Compass USA because it reconciled the fulfillment SO against the e | library/app/api/toga2.php, dbchanges2/Client_Compass/2026-07-22a - CleanupOfficeDepotDuplicatePurchaseOrderItems.sql |
 | [Recovering a Lost Compass ODP EDI 850 Import (re-drop from Logs.FileLog)](workflows/odp-edi-import-recovery.md) | 1.0 | How to recover a Compass **Office Depot EDI 850** import that failed partway — the case where cron **3a** created the ODP SalesOrder header, the follow-up item | worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, worker/schedules/cron.worker.sync.json |
-| [Compass ODP Order Pipeline to NetSuite (numbered worker crons)](workflows/odp-order-pipeline-to-netsuite.md) | 1.0 | The end-to-end **Compass Office Depot (ODP) order → NetSuite** pipeline as it actually runs through the 1.0 `worker` crons under `worker/crons/toga2/compass/`, | worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, worker/crons/toga2/compass/edi/1_download_edi_s3_create_po_toga.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, worker/schedules/cron.worker.sync.json, library/app/client/compass.php |
+| [Compass ODP Order Pipeline to NetSuite (numbered worker crons)](workflows/odp-order-pipeline-to-netsuite.md) | 1.0 | The end-to-end **Compass Office Depot (ODP) order → NetSuite** pipeline as it actually runs through the 1.0 `worker` crons under `worker/crons/toga2/compass/`, | worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php, worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php, worker/crons/toga2/compass/edi/1_download_edi_s3_create_po_toga.php, worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php, worker/crons/toga2/compass/workflow/4_transmit_office_depot_po_acknowledgements.php, worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php, worker/schedules/cron.worker.sync.json, library/app/client/compass.php |
 | [Compass Order Lifecycle & Data-Integrity Invariants](workflows/order-lifecycle-and-data-integrity.md) | 2.0 | End-to-end map of how a Compass order flows through the `Client_Compass` (2.0) database and the **expected raw-data shape** at each link/ASN/IF level. |  |
 | [Comparing Compass Persona/Catalogue Effects across prod and dev-sandbox](workflows/persona-population-env-comparison.md) | 2.0 | How to prove what a persona/catalogue change actually does to **100% of Compass USA users**, by diffing production against dev-sandbox. | test/@Bala/generate_persona_test_data.py, test/@Bala/persona-refactor-full-user-export.sql, test/@Bala/TRUE-75705-persona-refactor-test-plan.md |
 | [Compass USA Persona Refactor — 8-Phase Migration & Deploy Order (TRUE-75705)](workflows/persona-refactor-migration.md) | 2.0 | Splits Compass USA's catch-all persona **1 ("All")** into **Base** (the six printer bundles, held by *everyone* including Levy) and a new **Non-Levy** persona ( | dbchanges2/Client_Compass/2026-08-06 - PersonaRefactor.sql, dbchanges2/Client_Compass/2026-08-06 - PersonaRefactor-Verification.sql, worker2/Worker/Client/Compass/PeopleFile.php, test/@Bala/TRUE-75705-persona-refactor-test-plan.md |

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

@@ -0,0 +1,116 @@
+---
+title: Compass Office Depot EDI 855 Acknowledgement + Over-Quantity PO Guard
+framework: "1.0"
+repo: worker
+project: Worker
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-08-13
+owners: ["jcardinal"]
+files:
+  - worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php
+  - worker/crons/toga2/compass/workflow/4_transmit_office_depot_po_acknowledgements.php
+  - library/app/edi.php
+related:
+  - ../workflows/odp-order-pipeline-to-netsuite.md
+  - ../workflows/odp-duplicate-po-line-cleanup.md
+  - mits-po-transmission-to-vendors.md
+  - ../profile.md
+---
+
+## Summary
+How Compass acknowledges Office Depot (ODP) inbound **EDI 850** purchase orders with an
+**X12 855**, and the **over-quantity guard** that rejects a duplicate PO before it is ever
+imported. Two paths share one builder:
+
+- **Accept** — the normal case. Cron `4_transmit_office_depot_po_acknowledgements.php`
+  (every 15 min) picks up imported `PurchaseOrders` rows with `dtAcknowledged IS NULL` and
+  sends an accept 855, then stamps `dtAcknowledged`.
+- **Reject** — cron `3a_import_office_depot_purchase_orders.php` (the 850 importer, every 5
+  min) detects a PO whose quantities exceed the Compass sales-order demand, **rejects the
+  entire PO (never imports it)**, and sends a reject 855 **inline from the importer**.
+
+Both 855s are produced by the new shared 1.0-core method
+`App_Edi::buildOfficeDepotPurchaseOrderAcknowledgement855()` (`library/app/edi.php`).
+
+## The problem this guards against
+Office Depot began **re-sending an already-processed Compass sales-order line under a
+BRAND-NEW ODP PO number** — same item, doubling the quantity. Example: one Compass SO
+`MR244753` line was purchased twice, via ODP PO `41672697-1214` **and** `41665576-1214`.
+
+The importer's only prior duplicate guard de-duped on **exact PO number**, so a
+new-numbered duplicate sailed straight through and created a second downstream order —
+the same failure family as the [dual-catalog duplicate PO-line
+bug](../workflows/odp-duplicate-po-line-cleanup.md), but caused upstream by ODP re-sending,
+not by our reconciliation.
+
+## The over-quantity guard (`3a`, before any SO/PO creation)
+New helper **`officeDepotPurchaseOrderExceedsCompassDemand()`** runs **after** the existing
+same-PO-number de-dupe and **before** any SalesOrder/PurchaseOrder creation:
+
+- For each part number on the incoming 850, it sums the Compass SO's **ordered quantity
+  (ceiling)** and compares it against **all ODP PO quantity already chained to that Compass
+  SO plus this PO**.
+- **If any matched part exceeds demand, the ENTIRE PO is rejected** — nothing is imported —
+  and a reject 855 is sent.
+- **"First occurrence passes" rule** (uniform across MR / MA / SA order types): if the
+  Compass SO does not exist yet there is nothing to exceed, so the PO passes. This keeps the
+  guard order-type-agnostic.
+- **Parts not on the Compass SO are ignored** (no false rejects on unrelated lines).
+- The demand read uses a direct **read-only `db_prod_compass`** link (added this session),
+  with `App_Database::sqlEscape` on the SO number.
+
+The demand relay it walks is the standard ODP chain — Compass SO (top, e.g. `MR244753`) →
+Compass PO → ODP SO → ODP PO (leaf) — via the `SalesOrders_PurchaseOrders` and
+`PurchaseOrders_SalesOrders` bridges (the same 6-table join the acknowledgement cron uses).
+
+## Why the reject is sent inline, not by cron 4
+A rejected PO is **never persisted**, so cron 4 — which keys off `PurchaseOrders` rows with
+`dtAcknowledged IS NULL` — can never see it. The importer therefore **builds and sends the
+reject 855 itself** from the parsed EDI, through the same AS2 outbox the accept path uses
+(`agilant-as2`, prefix `OfficeDepot/OUTBOX/`). No schema change, no new/changed cron
+schedule.
+
+## The shared 855 builder (`App_Edi::buildOfficeDepotPurchaseOrderAcknowledgement855`)
+Additive to the 1.0 core (`library/app/edi.php`). Renders the X12 855 with an
+**accept/reject mode**:
+
+- **Accept** reproduces the previous cron output **byte-for-byte**.
+- **Reject** flips only two elements: **`BAK02` `AD` → `RD`** and **`ACK01` `IA` → `IR`**.
+- Envelope values are taken from the live accept path: **sender `2127360115`, receiver
+  `ODEPCC1`, interchange `000042405`**.
+
+Cron 4 was refactored to delegate accept-mode construction to this method
+(behavior-preserving: same query, logging, AS2 send, and `dtAcknowledged` stamp). The
+importer's reject path uses reject mode.
+
+## 850 REF round-trip (for tracing / builder inputs)
+The 850 carries the identifiers the 855 echoes back:
+- **`REF*CO`** — `productSpecificationDocumentNumber`
+- **`REF*QC`** — `internalSalesOrder`
+
+(See the [ODP order pipeline doc](../workflows/odp-order-pipeline-to-netsuite.md) for the
+full 850 → TOGa identifier map, incl. `BEG` = ODP PO number and `REF*QC` = the value to
+search on for the ODP SalesOrder.)
+
+## ⚠ 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
+expects different reject values it is a **one-line change** in the builder's reject branch.
+A legacy, abandoned sketch (`compass/edi/3_send_edi_855(reject).php`) used **non-standard**
+codes `BAK01 = A1` / `BAK02 = RE` — that path was **deliberately NOT followed**.
+
+## Change history
+- 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",
+  parts-not-on-SO ignored, read-only `db_prod_compass` link). Added shared
+  `App_Edi::buildOfficeDepotPurchaseOrderAcknowledgement855()` (accept byte-for-byte, reject
+  flips `BAK02` AD→RD + `ACK01` IA→IR); refactored cron 4 to use it (accept mode);
+  reject 855 sent inline from the importer via the AS2 outbox since a rejected PO is never
+  persisted. No schema/schedule change; both repos deployed (library before worker). Tests
+  skipped per developer. Reject codes pending confirmation against ODP's 855 companion guide.
+  (jcardinal)
+</content>
+</invoke>

package/knowledge/clients/compass-usa/profile.md

@@ -32,6 +32,7 @@ related:
   - features/approval-decision-flow.md
   - workflows/cross-kit-bundle-corruption.md
   - workflows/odp-duplicate-po-line-cleanup.md
+  - features/odp-edi-855-acknowledgement-and-overquantity-guard.md
   - ../../2.0/apps/worker2/features/compass-vip-support-importer.md
   - ../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
   - ../../2.0/apps/toga2-commerce/features/category-tile-sort-order.md
@@ -90,6 +91,12 @@ separate, related client (see its own profile).
   duplicate Office Depot PO lines backed by shadow VendorItems (4,886 dup lines / 1,320 POs).
   Root cause, forward fix, and the `2026-07-22a` cleanup migration:
   [ODP Duplicate PO-Line Cleanup](workflows/odp-duplicate-po-line-cleanup.md).
+- **ODP re-sends processed lines under new PO numbers (2026-08-13).** Office Depot began
+  re-sending an already-processed Compass SO line under a **brand-new** ODP PO number
+  (doubling quantity). The 850 importer (cron 3a) now runs an **over-quantity guard** that
+  rejects the whole PO and sends a reject **EDI 855**; ODP POs are acknowledged with an 855
+  (accept via cron 4, reject inline from 3a) built by a shared `App_Edi` method. See
+  [ODP EDI 855 Acknowledgement + Over-Quantity Guard](features/odp-edi-855-acknowledgement-and-overquantity-guard.md).
 - ASN ingestion entry points: cXML to the V2 API (logged in `Logs_Compass.Api`) and
   `worker/crons/toga2/compass/workflow/3b_import_strategic_systems_advance_shipping_notices.php`.
 

package/knowledge/clients/compass-usa/workflows/odp-order-pipeline-to-netsuite.md

@@ -7,16 +7,18 @@ client: compass-usa
 type: workflow
 status: active
 updated: 2026-08-04
-owners: ["rgirish", "bala", "dfranks"]
+owners: ["rgirish", "bala", "dfranks", "jcardinal"]
 files:
   - worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php
   - worker/crons/toga2/compass/workflow/2_transmit_mits_purchase_orders_to_vendors.php
   - worker/crons/toga2/compass/edi/1_download_edi_s3_create_po_toga.php
   - worker/crons/toga2/compass/workflow/3a_import_office_depot_purchase_orders.php
+  - worker/crons/toga2/compass/workflow/4_transmit_office_depot_po_acknowledgements.php
   - worker/crons/toga2/compass/workflow/5_create_netsuite_sales_orders_from_office_depot_purchase_orders.php
   - worker/schedules/cron.worker.sync.json
   - library/app/client/compass.php
 related:
+  - clients/compass-usa/features/odp-edi-855-acknowledgement-and-overquantity-guard.md
   - clients/compass-usa/workflows/odp-edi-import-recovery.md
   - clients/compass-usa/workflows/order-lifecycle-and-data-integrity.md
   - clients/compass-usa/features/mits-po-transmission-to-vendors.md
@@ -122,6 +124,26 @@ duplicates and backfills whatever is missing**:
    a **zero-item ODP SalesOrder sits in this queue retrying every 10 minutes** until its lines are
    restored — the retry loop is the symptom, not the cause.
 
+## The active flow is `workflow/` — the other ODP folders are legacy
+The **live** Office Depot EDI flow is entirely under
+`worker/crons/toga2/compass/workflow/`: **3a** import (every 5 min), **4** transmit-PO-
+acknowledgements (every 15 min), **5** create-NetSuite-SO, **6** generate-ASN. The folders
+`compass/edi/`, `compass/DOA_edi_odp_flow/`, and `compass/DOA_Scripts/` are **legacy /
+inactive** (this is why `edi/1` is dead code — see the correction above). In particular
+`compass/edi/3_send_edi_855(reject).php` is an abandoned sketch using **non-standard** reject
+codes (`BAK01=A1` / `BAK02=RE`) — **do not** follow it.
+
+- **Cron 4 — `workflow/4_transmit_office_depot_po_acknowledgements.php`** (every 15 min) sends
+  the **accept** X12 **855** for imported ODP `PurchaseOrders` with `dtAcknowledged IS NULL`,
+  then stamps `dtAcknowledged`. It delegates 855 construction to
+  `App_Edi::buildOfficeDepotPurchaseOrderAcknowledgement855()` (accept mode). A **reject** 855
+  is instead sent **inline from cron 3a** when the over-quantity guard rejects a PO (a rejected
+  PO is never persisted, so cron 4 can never see it). See
+  [ODP EDI 855 Acknowledgement + Over-Quantity Guard](../features/odp-edi-855-acknowledgement-and-overquantity-guard.md).
+- **Cron 3a now also runs an over-quantity guard** (`officeDepotPurchaseOrderExceedsCompassDemand()`)
+  after the same-PO-number de-dupe and before any SO/PO creation, rejecting a whole PO when ODP
+  re-sends an already-processed Compass SO line under a **new** PO number. Same doc.
+
 ## Cron 5 NetSuite SO creation — failure modes & the two ODP error emails
 
 Two different Compass ODP error emails exist, from **two different pipeline stages**. They look
@@ -193,6 +215,14 @@ wrong record makes every order look "stuck." Use the **join**, never a number ma
   transmission feature.)
 
 ## Change history
+- 2026-08-13 — Added **cron 4** (transmit ODP PO acknowledgements, every 15 min) and noted
+  **cron 6** (generate ASN); flagged the active `workflow/` folder vs the legacy
+  `compass/edi/`, `compass/DOA_edi_odp_flow/`, `compass/DOA_Scripts/` folders (incl. the
+  abandoned non-standard-reject `edi/3` sketch). Recorded cron 3a's new over-quantity guard
+  (rejects a whole PO when ODP re-sends a Compass SO line under a new PO number) and the shared
+  reject/accept 855 builder; details in the new
+  [855 Acknowledgement + Over-Quantity Guard](../features/odp-edi-855-acknowledgement-and-overquantity-guard.md)
+  feature. (jcardinal)
 - 2026-08-04 — **Corrected the 850-import step**: `edi/1_download_edi_s3_create_po_toga.php` is
   **dead code in no schedule**; the schedule entry named "Download EDI From S3 Files & Create PO -
   EDI Office Depot" (`*/5`) actually runs `workflow/3a_import_office_depot_purchase_orders.php`,

package/package.json

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