toga-ai 1.0.428 → 1.0.429

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

@@ -6,7 +6,7 @@ project: Worker
 client: nycdoe
 type: client-feature
 status: active
-updated: 2026-07-09
+updated: 2026-07-23
 owners: [mhammontree, sking]
 files:
   - worker/crons/sync/nycdoe/import_asn.php
@@ -248,6 +248,45 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
   164785 (internalId 6971859 → `38S0500` synced, 15 ROs) and PO 165751 (`50M7280` + `A3L980`
   NOT synced). PRs: library#831 (merge first) then worker#1670.
 
+- **⚠ REGRESSION of the 2026-07-09 multi-PO fix — a cross-wired SO/PO stamp silently drops
+  install tickets (diagnosed 2026-07-23; deferred to a one-off backfill, cron NOT changed).**
+  The 2026-07-09 fix (library#831 + worker#1670) made Stage 5 resolve item receipts **only**
+  Sales-Order-wide via `App_NetSuite::listItemReceiptsCreatedFromSalesOrder($soId)` (which fans
+  across the POs from `listPurchaseOrdersCreatedFromSalesOrder($soId)`). It **replaced** —
+  rather than augmented — the old by-stamped-PO lookup (`listItemReceiptsCreateFromPurchaseOrder`).
+  So when an ASN item's stamped `netSuiteInternalPurchaseOrderId` is **not a child of** its
+  stamped `netSuiteInternalSalesOrderId`, the SO-wide fan-out never inspects the stamped PO,
+  finds zero receipts, and the cron **silently creates no repair order and raises no error** —
+  the same "serials never sync, no error" symptom as the bug it replaced, in a distinct case.
+  - **Fingerprint:** an item stamped an SO whose only child PO has no receipt, while the stamped
+    PO (often an internalId *lower* than the SO's, i.e. created earlier) carries the real receipt
+    with the matching serials.
+  - **Root cause of the cross-wired stamp (SME Skyler King confirmed) = a warehouse
+    manual-entry error, not automation.** Confirmed case ASN **26215** (customer PO
+    `S202641365`): original SO `6901611` processed only `DOE-30HSS1BB00` (qty 1), PO `6901612`,
+    item receipt `6910404` (ticketed fine, RO 811791). Two monitors `DOE-62C5GAR1US` (serial
+    `VKWD9092`) and `DOE-64B6MAR1UZ` (serial `V600F9M6`) were **manually** added to SO `6901611`
+    with a **manually** created PO `6910401`, received on item receipt `6910410`. Separately,
+    when the real ASN arrived, the automation created a **duplicate** SO `6996287` (auto-PO
+    `6996288`, never used to receive — the serials were already on `6910410`). Net: ASN items
+    53905/53914 ended stamped SO=`6996287` (the duplicate) but PO=`6910401` (the manual PO under
+    the *original* SO), so SO-wide resolution finds nothing.
+  - **SME-confirmed correct end-state:** the units belong to the **original** SO (`6901611`);
+    the automation-created duplicate SO `6996287` / PO `6996288` is a NetSuite cleanup item
+    (cancel). The owed installs (one repair order per received unit) are **independent** of the
+    NetSuite duplicate and are created **TOGa Desk-side only**. Warehouse process has since been
+    corrected by training.
+  - **Recovery (chosen fix — one-off, not a cron change):** a run-once backfill reuses
+    `doeCreateInstallationRepairOrder` verbatim from Stage 5 (`3_create_installation_ticket.php`)
+    but scoped to a single ASN (id via CLI arg), resolving receipts from the **UNION** of the
+    SO's child POs *and* the item's stamped PO. It is idempotent (only units with
+    `togadeskRepairOrderId IS NULL`), guards double dispatch (skips a serial that already has a
+    `repair_order` in `db_togadesk`), never adds new `AdvanceShippingNoticeUnits`, is
+    serialized-only, and makes no NetSuite/ServiceNow writes. Confirmed on ASN 26215 (created the
+    two owed ROs). A **permanent union fix in the cron** (resolve receipts from SO child POs plus
+    the stamped PO) was considered but **deferred** — the team chose the one-off because the
+    warehouse process error is now prevented by training.
+
 ## Debugging & DB topology (DOE 1.0 sync)
 
 Reference for future DOE investigations — the 1.0 worker cannot run on a dev/Windows box;
@@ -265,6 +304,14 @@ use the toga DB MCP + `Logs.API` instead of running prod code locally.
   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.
+- **Stuck-vs-received check, per ASN item:** compare
+  `listItemReceiptsCreatedFromSalesOrder($stampedSO)` against
+  `listItemReceiptsCreateFromPurchaseOrder($stampedPO)`, dumping each receipt line's `itemName`
+  plus its `inventoryAssignment` serials. If the SO-wide call returns 0 but the stamped PO
+  returns the receipt with the matching serials, it is the cross-wired-stamp regression above.
+- **`App_Model_Core_AdvanceShippingNotice` does NOT map `dtCreatedInstallationTicket`** — its
+  `__get` throws "No field or quick query defined for key …". Read that column via **raw SQL**,
+  not the model.
 
 ## Operating rules when changing this integration
 
@@ -278,6 +325,17 @@ use the toga DB MCP + `Logs.API` instead of running prod code locally.
    of the consumer query; `php -l` every touched file.
 
 ## Change history
+- 2026-07-23 — Diagnosed a regression of the 2026-07-09 multi-PO fix: Stage 5's SO-wide receipt
+  resolution *replaced* the by-stamped-PO lookup, so a cross-wired stamp (an item's stamped PO
+  not a child of its stamped SO) silently drops install tickets with no error. Root cause of the
+  cross-wire = a warehouse manual-entry error (a duplicate SO was auto-created while the real
+  receipt sat under a manually-created PO on the original SO); SME Skyler King confirmed the
+  correct end-state (units on the original SO, duplicate SO cancelled, owed installs are TOGa
+  Desk-side only). Recovered stuck ASN 26215 with a one-off union-receipt backfill (union of SO
+  child POs + the stamped PO; idempotent; no NetSuite/ServiceNow writes) that created the two
+  owed ROs; a permanent union fix in the cron was considered but deferred (warehouse process now
+  corrected by training). Added a regression gotcha + two debugging notes. No production code
+  changed. (mhammontree; SME sking)
 - 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,

package/package.json

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