toga-ai 1.0.148 → 1.0.150

package/knowledge/2.0/apps/_underscore/features/recursive-item-fulfillments.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-06-08
-owners: [jcardinal]
+updated: 2026-06-19
+owners: [jcardinal, rgirish]
 files:
   - _underscore/Model/Client/ItemFulfillment.php
   - _underscore/Model/Client/ItemFulfillmentItem.php
@@ -101,15 +101,18 @@ inheritance. Verified against prod `Client_Compass` chains (≥3 levels deep).
   post-delete hooks never fire; a standalone downstream DELETE doesn't immediately remove its
   upstream mirror. A later reconciling PUT cleans up stale records via set comparison. Full
   delete handling would need a `preDelete` mechanism + `PRE/DELETE` interceptor rows.
+- **Transfer-order fulfillments are explicitly excluded from the upstream walk.** `reconcileUpstreamLevel()` returns `null` immediately when the downstream IF has `transferOrderId` set (no `salesOrderId`). This is intentional for standalone TOs (GroWrk v1). When SO→TO→SO chain scenarios are needed, Phase 5 of the GroWrk transfer order plan extends this method to walk `TransferOrders_SalesOrders` bridge tables — see `clients/growrk/features/transfer-order-flow.md`.
 - **Out of scope:** NetSuite sync of upstream IFs; transfer-order fulfillments
   (`transferOrderId`) are skipped.
 - **Performance:** every child write re-runs a full upstream walk (read-heavy, but each
   upstream record is written at most once — idempotent). Fine for normal fulfillment sizes.
 
 ## Change history
+- 2026-06-19 — Documented explicit TO exclusion in reconcileUpstreamLevel; cross-linked GroWrk transfer order plan. (rgirish)
 - 2026-06-08 — Documented the Recursive Item Fulfillments engine (interceptor-driven upstream fulfillment mirroring, bundle scaling, reconcile loop). (jcardinal)
 
 ## Related docs
+- GroWrk transfer order flow plan: `clients/growrk/features/transfer-order-flow.md`.
 - `_underscore` architecture (interceptors, `internalApiRequest`, `_Model` layer).
 - `api2` architecture (V2 metadata engine that fires these interceptors; the
   commit-logs / rollback-data-on-failure transaction invariant the throws rely on).

package/knowledge/INDEX.md

@@ -14,7 +14,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 8 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 9 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 8 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 4 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
@@ -38,6 +38,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **Compass Canada** (`compass-canada`) → [clients/compass-canada/INDEX.md](clients/compass-canada/INDEX.md)
 - **Compass USA** (`compass-usa`) → [clients/compass-usa/INDEX.md](clients/compass-usa/INDEX.md)
 - **Elite** (`elite`) → [clients/elite/INDEX.md](clients/elite/INDEX.md)
+- **GroWrk** (`growrk`) → [clients/growrk/INDEX.md](clients/growrk/INDEX.md)
 - **New York City Department of Education** (`nycdoe`) → [clients/nycdoe/INDEX.md](clients/nycdoe/INDEX.md)
 - **Office Depot** (`office-depot`) → [clients/office-depot/INDEX.md](clients/office-depot/INDEX.md)
 - **Prudential Financial** (`prudential`) → [clients/prudential/INDEX.md](clients/prudential/INDEX.md)

package/knowledge/clients/growrk/INDEX.md

@@ -0,0 +1,6 @@
+# Client: GroWrk `growrk`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Transfer Order Flow (NetSuite SalesOrder workaround → dedicated TransferOrders)](features/transfer-order-flow.md) | 2.0 | GroWrk moves inventory between their own locations (warehouses, distribution points). | _underscore/Model/Client/TransferOrder.php, _underscore/Model/Client/TransferOrderItem.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemReceipt.php, _underscore/Model/Client/ItemReceiptItem.php, _underscore/Trait/Netsuite/TransferOrder.php, dbchanges2/Client_Growrk/, dbchanges2/Client/ |
+| [GroWrk](profile.md) | 2.0 | GroWrk is a 2.0 client using TOGA for inventory and order management. |  |

package/knowledge/clients/growrk/features/transfer-order-flow.md

@@ -0,0 +1,119 @@
+---
+title: "Transfer Order Flow (NetSuite SalesOrder workaround → dedicated TransferOrders)"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: growrk
+type: client-feature
+status: active
+updated: 2026-06-19
+owners: ["rgirish"]
+files:
+  - _underscore/Model/Client/TransferOrder.php
+  - _underscore/Model/Client/TransferOrderItem.php
+  - _underscore/Model/Client/ItemFulfillment.php
+  - _underscore/Model/Client/ItemReceipt.php
+  - _underscore/Model/Client/ItemReceiptItem.php
+  - _underscore/Trait/Netsuite/TransferOrder.php
+  - dbchanges2/Client_Growrk/
+  - dbchanges2/Client/
+related:
+  - 2.0/apps/_underscore/features/recursive-item-fulfillments.md
+  - 2.0/apps/worker2/architecture.md
+---
+
+## Summary
+
+GroWrk moves inventory between their own locations (warehouses, distribution points). Historically this was done by creating zero-dollar SalesOrders with `holdInvoice=true` in NetSuite — polluting sales reporting, distorting demand planning, and creating audit confusion. This feature introduces a dedicated `TransferOrders` record type in the TOGA database. NetSuite continues to receive transfer orders as SalesOrders with `holdInvoice=true` (no NS-side change); the distinction is made and stored only on the TOGA side.
+
+## Key files / entry points
+
+| File | Role |
+|---|---|
+| `_underscore/Model/Client/TransferOrder.php` | TO model — origin/destination locations, number, serviceRequestId, purchaseOrderId, c_netsuiteInternalSalesOrderId |
+| `_underscore/Model/Client/TransferOrderItem.php` | TO line items — itemId, quantity, lineNumber |
+| `_underscore/Trait/Netsuite/TransferOrder.php` | NS sync trait — **currently a stub** (only declares c_netsuiteInternalSalesOrderId); `syncNetsuiteTransferOrder()` not yet implemented |
+| `_underscore/Model/Client/ItemFulfillment.php` | Outbound closure — `transferOrderId` FK already present; `salesOrderId` must be made nullable |
+| `_underscore/Model/Client/ItemReceipt.php` | Inbound closure — `transferOrderId` FK already present |
+| `dbchanges2/Client_Growrk/` | Client-specific schema fixes (dtCreated/dtUpdated/isActive on TransferOrders, nullable XOR columns) |
+| `dbchanges2/Client/` | All-client bridge tables (8 new SO↔TO and PO↔TO bridge tables) |
+
+## How it works
+
+### Identification signal
+A NetSuite SalesOrder is a TransferOrder if and only if: `holdInvoice === true` AND `total === 0`. Both conditions must hold — `holdInvoice` alone is not sufficient.
+
+### Two-stage closure
+- **Outbound:** An `ItemFulfillment` with `transferOrderId` set (not `salesOrderId`) closes the outbound side — items leave the origin location.
+- **Inbound:** An `ItemReceipt` with `transferOrderId` set (not `purchaseOrderId`) closes the inbound side — items arrive at the destination location.
+
+### Chain positions
+Transfer orders can sit in several positions in the order chain:
+1. **Standalone TO** — pure location-to-location move, no SO/PO involved
+2. **SO → TO** — customer SO triggers an internal TO (outbound from origin)
+3. **PO → TO** — vendor PO received via TO (move to warehouse)
+4. **SO → TO → SO** — customer-facing SO, internal move, downstream SO to fulfill
+
+## Data model
+
+### TransferOrders (prod — `Client_Growrk`)
+| Column | Type | Notes |
+|---|---|---|
+| id | int PK | |
+| uuid | char(36) | |
+| originLocationId | int FK | NOT NULL |
+| destinationLocationId | int FK | NOT NULL |
+| dateOrder | date | nullable |
+| number | varchar | currently varchar — generate as `TO-<tranId>` from NS in sync trait |
+| serviceRequestId | int FK | nullable |
+| purchaseOrderId | int FK | nullable |
+| customerIdentificationNumber | varchar | nullable |
+| c_netsuiteInternalSalesOrderId | varchar | NS SalesOrder internal ID |
+| **dtCreated** | datetime | **MISSING — must add in Phase 1** |
+| **dtUpdated** | datetime | **MISSING — must add in Phase 1** |
+| **isActive** | tinyint | **MISSING — must add in Phase 1** |
+
+### Columns that need schema fixes before first use
+- `ItemFulfillments.salesOrderId` — currently NOT NULL; must be made nullable (XOR with transferOrderId)
+- `ItemFulfillmentItems.salesOrderItemId` — currently NOT NULL; must be made nullable
+- `ItemReceiptItems.purchaseOrderItemId` — currently NOT NULL; must be made nullable (XOR with transferOrderItemId)
+
+### New bridge tables (all 8 in `dbchanges2/Client/` — applies to all clients)
+| Table | FK A | FK B |
+|---|---|---|
+| SalesOrders_TransferOrders | salesOrderId | transferOrderId |
+| TransferOrders_SalesOrders | transferOrderId | salesOrderId |
+| PurchaseOrders_TransferOrders | purchaseOrderId | transferOrderId |
+| TransferOrders_PurchaseOrders | transferOrderId | purchaseOrderId |
+| SalesOrderItems_TransferOrderItems | salesOrderItemId | transferOrderItemId |
+| TransferOrderItems_SalesOrderItems | transferOrderItemId | salesOrderItemId |
+| PurchaseOrderItems_TransferOrderItems | purchaseOrderItemId | transferOrderItemId |
+| TransferOrderItems_PurchaseOrderItems | transferOrderItemId | purchaseOrderItemId |
+
+`Core.Records` already has id=312 (`_Model_Client_TransferOrder`) and id=313 (`_Model_Client_TransferOrderItem`) registered.
+
+## Implementation plan (5 phases — team review pending)
+
+Full plan saved at `/Applications/AMPPS/www/transfer-order-plan.md`.
+
+| Phase | Work | Status |
+|---|---|---|
+| 1 | Schema fixes (dtCreated/dtUpdated/isActive, nullable XOR columns, 8 bridge tables, Core RecordFields) | Pending |
+| 2 | PHP model updates (TransferOrder.php fields, 8 bridge model stubs) | Pending |
+| 3 | _Trait_Netsuite_TransferOrder sync impl + ItemReceipt TO path | Pending |
+| 4 | worker2 _Worker_Netsuite_TransferOrder action class | Pending |
+| 5 | Upstream IF chain extension (SO→TO→SO walk) | Deferred |
+
+## Gotchas / known issues
+
+- **`dtCreated`/`dtUpdated` MISSING from `TransferOrders` in prod.** Any `_Model_Client_TransferOrder::save()` call will fail silently until Phase 1 runs. This is a hard blocker — nothing else works until the schema fix lands.
+- **XOR is application-layer only.** MySQL does not enforce that exactly one of `salesOrderId`/`transferOrderId` is set on `ItemFulfillments`. The sync trait and any POST interceptor must validate this explicitly.
+- **`_Trait_Netsuite_TransferOrder` is a stub.** It declares only `$c_netsuiteInternalSalesOrderId` — there is no `syncNetsuiteTransferOrder()` method yet.
+- **Upstream IF chain explicitly skips TOs today.** `ItemFulfillment::reconcileUpstreamLevel()` returns null when `transferOrderId` is set — the comment reads "no salesOrderId (transfer order) → return null (out of scope)". Phase 5 will extend this.
+- **Lazy transaction gotcha.** `_Database::register()` auto-starts a lazy transaction since Apr 2026. The worker must call `_Database::transactionCommit(DB_CLIENT)` before any SQS dispatch or the TO insert rolls back silently.
+- **Bridge table scope confirmed as all-clients.** The 8 bridge tables go in `dbchanges2/Client/` (not `Client_Growrk/`). Schema fixes (dtCreated etc.) stay in `Client_Growrk/` — other clients don't need them.
+- **NS identification: both conditions required.** `holdInvoice=true` alone is not a safe signal — must also confirm `total === 0`.
+
+## Change history
+
+- 2026-06-19 — Designed full transfer order flow; confirmed DB state in prod; produced 5-phase implementation plan pending team review (rgirish)

package/knowledge/clients/growrk/profile.md

@@ -0,0 +1,22 @@
+---
+title: "GroWrk"
+framework: "2.0"
+apps:
+  - _underscore
+  - api2
+  - worker2
+  - dbchanges2
+project: _Underscore
+client: growrk
+type: profile
+status: active
+updated: 2026-06-19
+owners: ["rgirish"]
+files: []
+related:
+  - clients/growrk/features/transfer-order-flow.md
+---
+
+## Summary
+
+GroWrk is a 2.0 client using TOGA for inventory and order management. Their primary integration involves inventory movements between locations (warehouses, distribution points). NetSuite is the ERP. The key engineering challenge is that GroWrk historically used zero-dollar SalesOrders with holdInvoice=true in NetSuite as a workaround to represent internal inventory transfers — work is underway to replace this with a dedicated TransferOrders record type in the TOGA DB while keeping NetSuite unchanged.

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.148",
+  "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",