toga-ai 1.0.148 → 1.0.149

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/package.json

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