toga-ai 1.0.604 → 1.0.605

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

@@ -6,7 +6,7 @@ project: Worker
 client: nycdoe
 type: client-feature
 status: active
-updated: 2026-08-17
+updated: 2026-08-18
 owners: [mhammontree, sking]
 files:
   - worker/crons/sync/nycdoe/import_asn.php
@@ -326,7 +326,7 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
   counts SO+customerPO pairs rather than distinct SOs.
 
 - **⚠ NAMED PATTERN — "Pre-ASN Manual Receipt Mismatch"** (the umbrella condition covering
-  this doc's two SO/PO-stamp gotchas below plus a third confirmed instance). Search this
+  this doc's two SO/PO-stamp gotchas below plus a third and fourth confirmed instance). Search this
   title, or its informal name **"Shipment Received Notice"** (Mark's nickname — some vendors,
   chiefly Lenovo, effectively send the ASN *after* the goods already arrived).
   - **Common shape:** a manufacturer's physical shipment reaches the warehouse before (or
@@ -343,6 +343,66 @@ Vendor SFTP ───(legacy_import_asn.php, ser+non-ser)─┘      [UNIQUE ded
     `listItemReceiptsCreateFromPurchaseOrder($actualReceiptPO)`) and both are fixed the same
     way (a `dbchanges` data repair repointing the ASN item row's SO/PO ids to wherever the
     receipt actually lives, then letting the `*/5` Stage 5 cron ticket it — no code change).
+  - **⚠ FIRST TRIAGE STEP — "is the receipt-bearing PO a `Created From` CHILD of a sales order
+    we can stamp?"** (added 2026-08-18). This one question picks the remedy, and the two
+    remedies are **not interchangeable**, because Stage 5 resolves receipts **SO-wide only**
+    (`listPurchaseOrdersCreatedFromSalesOrder` → receipts per child PO):
+    - **PO IS a child of the SO** → a plain data repoint of *both* id columns
+      (`netSuiteInternalSalesOrderId` + `netSuiteInternalPurchaseOrderId`) works, and the `*/5`
+      Stage 5 cron tickets it itself. (Instances 3 and 4.)
+    - **PO is NOT a child** — a manually created PO or a cross-wired stamp, e.g. ASN `26215` —
+      → the SO-wide fan-out can **never** reach it, so a repoint is a **silent no-op** and
+      recovery needs the one-off **union-receipt backfill** instead.
+    Answer it in one look via NetSuite's **"Related Records"** tab on the SO (it lists the child
+    POs and their link type, e.g. `Special Order`), confirmed by the PO's own **"Created From"**
+    field. Getting this wrong costs a full apply-and-wait cron cycle before you learn the
+    repoint did nothing.
+  - **Quick discriminators that rule out neighbouring DOE failure classes** (use these before
+    committing to this pattern):
+    - A unit with `trackingNumberId` **NOT NULL** was created by the **importer**, not added by
+      Stage 5 from NetSuite — i.e. a genuine ASN unit (the inverse of the dedupeKey-drift
+      fingerprint further below).
+    - A well-formed `serialNumber` + populated `assetTag` + a clean OEM SKU in `partNumber`
+      rules **out** the open "Lenovo Off-Layout ASN File" parse bug (whose fingerprint is
+      `serialNumber = '1'`, the real serial in `assetTag`, and a product *description* in
+      `partNumber`).
+    - **NetSuite internal ids are creation-ordered**, so a receipt id can never predate its own
+      PO id — that ordering alone can disprove a proposed receipt↔PO pairing.
+  - **Confirmed instance 4 — NEW STRUCTURAL VARIANT: duplicate SO cut for a POST-FREEZE GROWTH
+    row while the ORIGINAL SO already carried that line** (2026-08-18, ASN `26644`, customer PO
+    `WR260175404-RPL`, Lenovo, `ldaCode` `M366M263`). Item `54552` (`DOE-62C5GAR1US`, unit
+    `604254`, serial `VKVY4802`, asset `DOE-LN1271004`) sat `installTicketStatus=pending` with
+    `togadeskRepairOrderId` NULL since 2026-07-02 — the silent-stranding dead end, no error, no
+    alert.
+    - Warehouse **force-received** the shipment because Lenovo's ASN had not arrived yet.
+    - SO `281110` (internal `7219711`) carried **all three** ASN lines including
+      `DOE-62C5GAR1US`, with two child POs, both link type **Special Order**: `167882`
+      (internal `7219712`, 7/1/2026) and `167917` (internal `7223073`, 7/2/2026). Goods were
+      receipted on PO `167917` / internal `7223073`, **item receipt internal `7223075`**.
+    - When the ASN growth row for the touch monitor landed (post-freeze growth correctly
+      becoming a fresh item row per business rule 4), the automation cut a **second** SO —
+      internal `7245587` / PO `7245588` — and Stage 3 stamped item `54552` with it. That
+      duplicate chain was never received and **never can be**: serial `VKVY4802` was already
+      consumed by receipt `7223075`. Id ordering confirms it: `7223073 < 7223075 < 7245587`.
+    - **Fix (data-only, worked 2026-08-18):** repointed `netSuiteInternalSalesOrderId`
+      `7245587 → 7219711` and `netSuiteInternalPurchaseOrderId` `7245588 → 7223073`; the `*/5`
+      Stage 5 cron then created the repair order itself. Because the correct chain's PO **is** a
+      legitimate `Created From` child of the SO, the plain repoint was the right remedy.
+    - **How it differs from its neighbours:** instance 3 (ASN `23522`) was a same-ASN **sibling
+      PO**; ASN `26215` had a **manually created** PO that was *not* a child of the stamped SO.
+      Here the duplicate arose from the **post-freeze growth rule itself** on an SO that already
+      held the line — no manual NetSuite edit involved.
+    - **⚠ OUTSTANDING (not done):** the orphaned duplicate chain SO internal `7245587` / PO
+      internal `7245588` is unreceived and unused and **should be cancelled in NetSuite**, same
+      as the duplicate chain on ASN `26215`. Not blocking the install, which is TOGa Desk-side
+      only.
+  - **Delivering the repair by hand vs. by `dbchanges`.** Instance 4 was run as a **manual
+    one-row `UPDATE` directly against legacy `Core`** — deliberately *not* shipped as a
+    `dbchanges` file, diverging from the ASN `26280` / `23522` precedents. Consequence worth
+    knowing: when run manually the **derived-table preflight guard is unnecessary** — that
+    pattern exists only to work around the `dbchanges` runner's inability to express procedural
+    guards. Pinning the before-state values in the `WHERE` clause still gives the
+    no-op / no-double-apply safety either way.
   - **Confirmed instance 3 (2026-08-06/07, ASN `23522`, customer PO `S202637409`).** Item
     `51104` (`DOE-63D8MAR3US`, serial `VTV11634`, asset `DOE-LN1262287`) arrived from Lenovo
     and the warehouse receipted *a* unit of that part against sibling PO **#157026** (internal
@@ -587,6 +647,22 @@ the client's `apps:` scope solely so this monitor loads, and its presence is **n
    of the consumer query; `php -l` every touched file.
 
 ## Change history
+- 2026-08-18 — Repaired stranded ASN `26644` / customer PO `WR260175404-RPL` (**data-only, no code
+  in `worker` or `dbchanges`**): item `54552` (`DOE-62C5GAR1US`, unit `604254`, serial `VKVY4802`)
+  had been `pending` with a NULL `togadeskRepairOrderId` since 2026-07-02. Repointed
+  `netSuiteInternalSalesOrderId` `7245587 → 7219711` and `netSuiteInternalPurchaseOrderId`
+  `7245588 → 7223073` and let the `*/5` Stage 5 cron ticket it (confirmed working). Logged this as
+  the **fourth** confirmed instance of "Pre-ASN Manual Receipt Mismatch" and a **new structural
+  variant**: the duplicate SO was cut for a **post-freeze growth row** while the original SO already
+  carried that line (no manual NetSuite edit) — distinct from instance 3's same-ASN sibling PO and
+  from ASN `26215`'s non-child manual PO. Added the pattern's **first triage step** ("is the
+  receipt-bearing PO a `Created From` child of a stampable SO?" — child ⇒ repoint works, non-child ⇒
+  repoint is a silent no-op and the union-receipt backfill is required), the quick discriminators
+  that rule out the off-layout parse bug and importer-vs-Stage-5 units, the id-ordering proof, and
+  the note that a **manual** SQL run needs no derived-table preflight guard (unlike a `dbchanges`
+  file). **Outstanding:** duplicate chain SO `7245587` / PO `7245588` still needs cancelling in
+  NetSuite. The durable detection/alerting fix for this stranding class remains **unbuilt**.
+  (mhammontree)
 - 2026-08-17 — TRUE-80587: added `Monitor/Nycdoe/ServiceNowEndpointHealth` (worker2 → OneUptime), an
   unauthenticated-GET liveness probe complementing the log-scraping 1.0 `App_SystemMonitor_ServiceNow*`
   monitors, which cannot see a dead endpoint. Token validity is a deliberately accepted coverage gap

package/package.json

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