toga-ai 1.0.809 → 1.0.810

package/knowledge/1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-09-14
+updated: 2026-09-15
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -1270,6 +1270,50 @@ library (or vice versa) crashes GroWrk and Adyen on their next sync run.
   Note `SalesOrderItems.lineNumber` is a **`smallint`**, so the parked base must stay within smallint
   range for the client's line counts (headroom 1000 is safe at observed volumes).
 
+- **⚠ A NetSuite-removed line that still holds an UPSTREAM customer-PO link blocked the renumber and
+  re-froze Compass SALES_ORDERS (fixed 2026-09-15, `library` only, Compass-gated).** Compass USA's
+  SALES_ORDERS was stuck at `1-RUNNING` (`Logs.Issue` 749, clientId 2) throwing *"unresolvable
+  NetSuite<->DB lineNumber conflict … reconcile the orphaned/undeletable row"* whenever a
+  NetSuite-removed line sat on a `lineNumber` a surviving line had to move onto. Root cause: the
+  **existing** stale-line prune (`toga2.php` ~L1582) runs **AFTER** the renumber **and** skips any
+  line carrying a PO link (it cannot delete a PO-linked line), so those removed-but-PO-linked lines
+  survived and occupied a needed target number — and the renumber threw first anyway.
+  - **Fix — a Compass-gated prune BEFORE the renumber** in `syncSalesOrderFromNetsuite`. For each SO
+    line whose `c_netsuiteLineUniqueKey` is **non-empty** and **absent** from the current NetSuite
+    line set (a line NetSuite removed) that was **never fulfilled and never invoiced**: delete its
+    Agilant-side SO↔PO **bridge LINK** rows in **both** directions (routes
+    `/purchase-order-item-sales-order-items/{uuid}` and `/sales-order-item-purchase-order-items/{uuid}`),
+    then DELETE the `SalesOrderItem` (`/sales-order-items/{uuid}`), then drop it from the in-memory
+    `$salesOrderItemsInToga`. It **NEVER** deletes/modifies the `PurchaseOrder`/`PurchaseOrderItem`
+    itself (the Compass **customer** order is off-limits) and never touches another order record.
+  - **Guardrails (owner decision 2026-09-15; cto AGREE; php-reviewer clean; cso SAFE TO SHIP):**
+    (a) non-empty key **absent from NetSuite** only — an empty key was never matched to NetSuite, so
+    treating it as "removed" is a false positive; (b) never a shipped/invoiced line (checked against
+    the fulfillment/invoice maps built ~L990-1032); (c) **Compass-gated** (`CLIENT_UUID_COMPASS`);
+    (d) **re-check that one line's fulfillment/invoice status immediately before the deletes** to
+    close a TOCTOU gap (the maps are a start-of-run snapshot); (e) the final `SalesOrderItem` DELETE
+    stays **throwing** (fail-loud) if any unhandled attachment remains — mirrors the PO-line cleanup
+    in `syncPurchaseOrderFromNetsuite` (~L2793-2806) and the mirror-NetSuite decision (2026-09-02).
+  - **Every FK child of `Client_Compass.SalesOrderItems` blocks a delete.** All are `NO ACTION` or
+    `RESTRICT`, and InnoDB treats `NO ACTION` as `RESTRICT`: `ItemFulfillmentItems`, `InvoiceItems`,
+    `PurchaseOrderItems_SalesOrderItems`, `SalesOrderItems_PurchaseOrderItems`,
+    `SalesOrderItems_CommittedUnits`, `SalesOrderItems_Tags`, `SalesOrderItems`
+    (`parentSalesOrderItemId` kit children), `SalesOrderItems_TransferOrderItems`,
+    `TransferOrderItems_SalesOrderItems`. This is why the prune must clear the bridge links first and
+    only ever touches never-fulfilled/never-invoiced lines.
+  - **Proven (evidence):** NetSuite sales order 271929 (internal id 6926956), customer "6096 ODP
+    Veyer (B2B)"; NetSuite reorganized it to 9 lines and removed 6 kitting lines (lineUniqueKeys
+    20024694/695/696/702/703/704) that never shipped and were never invoiced but each still held an
+    upstream customer-PO link — those 6 blocked the renumber.
+  - **⚠ OPEN, NOT FIXED — a DUPLICATE `SalesOrders` record on one NetSuite internal id.** `SalesOrders`
+    number **467435086001** shares NetSuite internal id **6926956** with order 271929 (two TOGa
+    records for one NetSuite sales order; 467435086001 has 12 keyless lines with downstream vendor-PO
+    links, none shipped). The main SO lookup in `syncSalesOrderFromNetsuite` (~L946-974) filters
+    Compass by `locationId 615286` / `customerId 3`, which currently narrows to 271929, so the prune
+    only ever touches 271929 — but **two records on one NetSuite id is an anomaly that could make the
+    lookup bind to the wrong record on other orders.** Needs its own ticket. Deploy: `library` only;
+    the worker redeploys to pick it up (worker clones library on deploy).
+
 - **⚠ Canon + Endeavor Health ITEM_RECEIPTS froze because `fetchPurchaseOrderById` never populated the
   PO vendor (deployed/verified 2026-08-29).** The PO shim's `->entity` was always null (its SuiteQL
   SELECT omitted `entity`, unlike `listPurchaseOrders`), so the fail-loud missing-entity guard in
@@ -1581,6 +1625,21 @@ library (or vice versa) crashes GroWrk and Adyen on their next sync run.
 
 ## Change history
 
+- 2026-09-15 — **Compass SALES_ORDERS unfrozen: a Compass-gated prune runs BEFORE the renumber.**
+  `syncSalesOrderFromNetsuite` was throwing *"unresolvable NetSuite<->DB lineNumber conflict"*
+  (`Logs.Issue` 749, clientId 2) because a NetSuite-removed line that still held an upstream
+  customer-PO link survived the existing stale-line prune (which runs after the renumber and skips
+  PO-linked lines) and occupied a `lineNumber` a surviving line needed. Added a prune BEFORE the
+  renumber that, for each never-fulfilled/never-invoiced line whose non-empty `c_netsuiteLineUniqueKey`
+  is absent from NetSuite, deletes its SO↔PO bridge links in both directions then the `SalesOrderItem`
+  — never touching the `PurchaseOrder`/`PurchaseOrderItem` (Compass customer order). Guardrails:
+  absent-from-NetSuite + non-empty key only, never shipped/invoiced, Compass-gated, immediate
+  TOCTOU re-check, final DELETE stays fail-loud. Recorded that every FK child of
+  `Client_Compass.SalesOrderItems` is `NO ACTION`/`RESTRICT` (all block a delete), and an OPEN
+  duplicate-`SalesOrders`-record anomaly (467435086001 shares NetSuite internal id 6926956 with
+  271929). Proven on NetSuite SO 271929 (6 removed kitting lines blocked the renumber). `library`
+  only, no SQL; worker redeploys to pick it up. cto AGREE; php-reviewer clean; cso SAFE TO SHIP.
+  (jcardinal)
 - 2026-09-13 — **ITEM_FULFILLMENTS unfrozen for NYCHH: five stacked fulfillment-reconcile bugs fixed
   (library, deployed + verified in prod).** (1) **Unit duplication from a truncated nested GET** — the
   existing-units dedup map was built from the nested `itemFulfillmentItemUnits` of one

package/knowledge/2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-26
-owners: [apeterson, bala]
+updated: 2026-09-15
+owners: [apeterson, bala, jcardinal]
 files:
   - _underscore/Model/Client/PurchaseOrders/SalesOrder.php
   - _underscore/Model/Client/SalesOrders/PurchaseOrder.php
@@ -40,6 +40,18 @@ one returns `200` with an empty array, which reads like a permission or data bug
 Read the name as **"`<source>`\_`<thing created from it>`"**. The *first* table name is the
 origin; the second is what was generated from it.
 
+**The line-item bridges follow the same rule (same name order, same directions):**
+
+| Table | Direction | Meaning | API route |
+|---|---|---|---|
+| `PurchaseOrderItems_SalesOrderItems` | **UPSTREAM** | an SO line created **FROM** a customer PO line | `purchase-order-item-sales-order-items` |
+| `SalesOrderItems_PurchaseOrderItems` | **DOWNSTREAM** | a vendor PO line created **FROM** an SO line | `sales-order-item-purchase-order-items` |
+
+The 1.0 Compass NetSuite sync deletes these **item-level** link rows in **both** directions when it
+prunes a NetSuite-removed SO line — see
+[NetSuite → TOGa Supply per-client sync](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md)
+(2026-09-15).
+
 ## How it works
 
 - Both `Records` rows are `aclDatabase = CLIENT`, `childPolicy = MATCH_UPSERT`, so both are
@@ -122,6 +134,11 @@ everywhere. Present is not populated.
   collapses many POs without multiplying rows.
 
 ## Change history
+- 2026-09-15 — Added the **line-item** bridge parallel: `PurchaseOrderItems_SalesOrderItems`
+  (upstream, route `purchase-order-item-sales-order-items`) and `SalesOrderItems_PurchaseOrderItems`
+  (downstream, route `sales-order-item-purchase-order-items`) follow the same name-order rule as the
+  header bridges. Confirmed while building the Compass 1.0 sync's pre-renumber prune, which deletes
+  both item-level link directions for a NetSuite-removed SO line. (jcardinal)
 - 2026-08-26 — Added the **write** side: the two directions are populated by two different
   pipelines (2.0 `_Trait_Netsuite_SalesOrder` writes **upstream** customer POs from `otherRefNum`;
   the 1.0 `syncPurchaseOrderFromNetsuite` cron writes **downstream** vendor POs), and the api2 child

package/package.json

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