toga-ai 1.0.149 → 1.0.150

package/knowledge/clients/nycdoe/INDEX.md

@@ -2,5 +2,5 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
-| [NYCDOE ServiceNow / ASN Integration](features/servicenow-integration.md) | 1.0 | The NYCDOE/ServiceNow integration mirrors DOE's ServiceNow tickets (Incidents + RITMs) into local tables, turns vendor shipment notices into NetSuite Sales Orde | worker/crons/sync/nycdoe/import_asn.php, worker/crons/sync/nycdoe/import_inc.php, worker/crons/sync/nycdoe/legacy_import_asn.php, worker/crons/sync/nycdoe/legacy_process_asn_queue.php, worker/crons/sync/nycdoe/process_tickets.php, 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/send_ticket_updates.php, worker/crons/sync/nycdoe/send_request_item_updates.php, worker/crons/sync/nycdoe/send_nycdoe_proof_of_delivery.php, worker/crons/sync/nycdoe/sync_nycdoe_locations.php, worker/crons/sync/nycdoe/receive_edi_purchase_orders.php, worker/crons/sync/nycdoe/send_edi_open_invoices.php, worker/crons/notifications/nycdoe/, worker/schedules/cron.worker.sync.json, worker/schedules/cron.worker.notification.json, library/app/api/nycdoe.php, library/app/api/nycdoev2.php, library/app/asnprocessor/manufacturer.php, library/app/edi.php |
+| [NYCDOE ServiceNow / ASN Integration](features/servicenow-integration.md) | 1.0 | The NYCDOE/ServiceNow integration mirrors DOE's ServiceNow tickets (Incidents + RITMs) into local tables, turns vendor shipment notices into NetSuite Sales Orde | worker/crons/sync/nycdoe/import_asn.php, worker/crons/sync/nycdoe/import_inc.php, worker/crons/sync/nycdoe/legacy_import_asn.php, worker/crons/sync/nycdoe/legacy_process_asn_queue.php, worker/crons/sync/nycdoe/process_tickets.php, 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/send_ticket_updates.php, worker/crons/sync/nycdoe/send_request_item_updates.php, worker/crons/sync/nycdoe/send_nycdoe_proof_of_delivery.php, worker/crons/sync/nycdoe/sync_nycdoe_locations.php, worker/crons/sync/nycdoe/receive_edi_purchase_orders.php, worker/crons/sync/nycdoe/send_edi_open_invoices.php, worker/crons/notifications/nycdoe/, worker/schedules/cron.worker.sync.json, worker/schedules/cron.worker.notification.json, library/app/api/nycdoe.php, library/app/api/nycdoev2.php, library/app/asnprocessor/manufacturer.php, library/app/asnprocessor/apple.php, library/app/asnprocessor/lenovo.php, library/app/asnprocessor/lexmark.php, library/app/asnprocessor/acer.php, library/app/edi.php |
 | [New York City Department of Education](profile.md) | 1.0 | NYC DOE (New York City Department of Education) is a TOGA client whose entire integration runs in the **1.0 worker tier** (~30 cron scripts under `worker/crons/ |  |

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

@@ -6,7 +6,7 @@ project: Worker
 client: nycdoe
 type: client-feature
 status: active
-updated: 2026-06-10
+updated: 2026-06-19
 owners: [mhammontree]
 files:
   - worker/crons/sync/nycdoe/import_asn.php
@@ -29,6 +29,10 @@ files:
   - library/app/api/nycdoe.php
   - library/app/api/nycdoev2.php
   - library/app/asnprocessor/manufacturer.php
+  - library/app/asnprocessor/apple.php
+  - library/app/asnprocessor/lenovo.php
+  - library/app/asnprocessor/lexmark.php
+  - library/app/asnprocessor/acer.php
   - library/app/edi.php
 related:
   - ../profile.md
@@ -147,10 +151,49 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
 4. **The NetSuite freeze:** `netSuiteInternalSalesOrderId IS NOT NULL` ⇒ `qtyOrder` locked.
    Growth = new item row; decrease = discrepancy alert, never a reduction.
 5. **One unit per non-serialized item row** — a 50-cable line is 1 unit and 1 repair order.
-6. **The `-RPL` PO suffix** forces a brand-new ASN/MSO/RO chain for replacements.
+6. **The replacement PO suffix forces a brand-new ASN/MSO/RO chain** for replacements —
+   but the suffix is a **per-manufacturer convention with NO standard format**, and even a
+   single manufacturer is inconsistent. Observed in prod: `-RPL`, `-REPL`, `-RPLE`, `-N`,
+   `_N` (underscore), and a space variant (` RPL`). ServiceNow itself documents NO `-RPL`
+   convention — its native replacement model is field-based on the *original* RITM
+   (`device_replaced`/`replaced_serial_number`/`replaced_asset_tag`); the suffix comes from
+   the OEM/SFTP feeds. Replacement-of-replacement appears as `-RPL-RPL` and is structurally
+   fine **only if hyphenated consistently**. See the duplicate-fulfillment gotcha below.
 
 ## Gotchas / known issues
 
+- **⚠ OPEN BUG (investigated 2026-06-19, not yet fixed) — manufacturer PO-suffix format
+  variance causes DUPLICATE fulfillment.** Stage 2's serialized dedupe is scoped to the
+  *exact* PO string (`lookupAsnUnitIdByAsnPartNumberAndSerialNumber[vendorId][purchaseOrder]
+  [part][serial]`, `legacy_process_asn_queue.php:272`), and the PO flows **verbatim** end to
+  end — never trimmed/normalized except Lenovo's `trim()` in `asnprocessor/lenovo.php`. So when
+  a manufacturer re-sends the *same physical unit* under a different suffix spelling
+  (e.g. Lenovo `WR260150152-RPL` then `WR260150152-RPLE`, same serial `V60095WK`), the two PO
+  strings differ → the serial guard misses → a full duplicate ASN→SO→MSO→RO chain is created
+  for one device (two NetSuite SOs, two repair orders, two onsite tickets).
+  - **Confirmed live case:** PO `WR260150152`, serial `V60095WK`, asset `DOE-LN1265478` →
+    repair orders **772308** (MSO 309909, via `-RPL`) and **801064** (MSO 318945, via `-RPLE`),
+    both `ORDER_ASSIGNED_AWAITING_SCHEDULING` (uncaught as of investigation), same TOGa Desk
+    `serialNumId 592519`.
+  - **Systemic, not a one-off:** ~14 same-base/same-serial duplicate pairs across **Lenovo AND
+    Lexmark**, spanning suffix forms `-RPL`/`-REPL`/`-RPLE`/`-N`/`_N`. A genuine replacement
+    carries a *new* serial, so identical-serial-across-base-and-suffix = true duplication.
+  - **The discriminator that would have caught it:** serial + assetTag + trackingNumber were
+    identical across copies. A serial-anchored dedupe (`vendorId + partNumber + serialNumber`,
+    ignoring PO suffix) collapses these; PO-scoped dedupe cannot.
+  - **Do NOT blindly canonicalize all suffixes to one token** — `-RPL-RPL` (legit
+    replacement-of-replacement) must stay distinct from `-RPL`. Confirm suffix semantics with
+    the SME before any fix.
+  - **Two ADJACENT anomalies surfaced by the same blast-radius query** (separate mechanisms,
+    not yet investigated): (a) a large Lexmark cluster pairing a **numeric order number with a
+    WR PO** for identical serials (e.g. `3100157`↔`WR240178018`) — same devices under two PO
+    identifiers; (b) **invalid/placeholder serials** becoming serialized units — serial `"NA"`
+    spans 25 POs→15 ROs (Lenovo `NA`→`''` normalization at `asnprocessor/lenovo.php:102` not
+    catching all), plus `"1"`, `"11"–"29"`.
+  - **Open thread for resume:** check RO active/cancelled status across the ~14 suffix-variance
+    pairs to size live double-truck-roll exposure; then trace the numeric-PO↔WR cluster.
+    Investigation was **read-only** — no code or data changes made.
+
 - **The queue `dedupeKey` format is load-bearing.** A 2026 incident (WR260236464 duplicate
   repair order) was caused by dedupeKey format drift (4-part keys with serial vs 3-part
   without) letting old rows re-import; Stage 2 then created a sibling item row (frozen
@@ -187,6 +230,7 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
    of the consumer query; `php -l` every touched file.
 
 ## Change history
+- 2026-06-19 — Investigated (read-only) the replacement-PO-suffix duplicate-fulfillment bug: PO-scoped serial dedupe defeated by per-manufacturer suffix-format variance (`-RPL`/`-REPL`/`-RPLE`/`-N`/`_N`); confirmed live case WR260150152/V60095WK (ROs 772308+801064) and ~14 systemic pairs across Lenovo+Lexmark. Refined business rule #6; added OPEN-BUG gotcha + adjacent anomalies (numeric-PO↔WR cluster, "NA"/integer serials). No code changes. (mhammontree)
 - 2026-06-10 — Documented the NYC DOE ServiceNow/ASN integration (ticket mirror, dual ASN ingestion, NetSuite freeze pipeline, EDI surface, dedupeKey gotchas). (mhammontree)
 
 ## Related docs

package/package.json

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