toga-ai 1.0.697 → 1.0.699

package/knowledge/1.0/apps/library/features/netsuite-suiteql-api-reference.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-19
+updated: 2026-08-29
 owners: ["dfranks", "jcardinal", "kyalamarthi"]
 files:
   - library/app/api/netsuite/rest.php
@@ -16,6 +16,7 @@ related:
   - netsuite-suiteql-rest-shim.md
   - ../architecture.md
   - ../../worker/features/forecast2-netsuite-reconciliation.md
+  - ../../../clients/nychh/features/netsuite-inventory-adjustment-fulfillment-link.md
 ---
 
 ## Summary
@@ -219,6 +220,22 @@ Other JE line facts (same probes):
 > NetSuite custom field supplying those dimensions is created and populated (no `salesrep` column, no
 > `item`). Re-evaluate only once that custom field exists — don't re-probe this from scratch.
 
+### Item Fulfillment (`ItemShip`) lines — ~3 rows per fulfilled item, and `mainline` is NOT the filter
+
+For an Item Fulfillment (`transaction.type = 'ItemShip'`), `transactionline` returns **~3 rows per
+fulfilled item**: the order-linked line, a positive "wash" line, and an `isinventoryaffecting = 'T'`
+line. **Only the order-linked line maps to a source-order line.** Keep exactly that one by requiring
+a `previoustransactionlinelink` of type `SalesOrd`/`TrnfrOrd` (via an `EXISTS` correlated subquery),
+and derive the source `orderLine` from that link's `previousline` (a correlated subquery — see the
+`previousTransactionLineLink` section below).
+
+- **⚠ `mainline = 'F'` is the WRONG filter for an ItemShip line.** NetSuite sometimes marks the
+  first real fulfilled line `mainline = 'T'`, so a `mainline='F'` predicate **silently drops it**.
+  Filter on the `SalesOrd`/`TrnfrOrd` line-link instead, not on `mainline`. (Same "extra posting
+  lines per item" shape as the credit-memo/cash-refund COGS lines in
+  `netsuite-suiteql-rest-shim.md`.) Surfaced building
+  [NYCHH inventory-adjustment → item-fulfillment linking](../../../clients/nychh/features/netsuite-inventory-adjustment-fulfillment-link.md).
+
 ## `previousTransactionLineLink` table
 
 The bridge between a child line (e.g. invoice) and its originating parent line (e.g. SO).
@@ -322,6 +339,39 @@ Used for fields SuiteQL doesn't expose on `transaction`: `shippingCost`, `taxTot
   `linesequencenumber` can diverge from REST `line` for SOAP-era records (confirmed empirically),
   so keying on `linesequencenumber` risks duplicate Sales rows that can't be matched or deleted.
   **`listSales()` keeps the per-id GET for this reason — do not eliminate it.**
+- **⚠ REST record SUBLIST endpoints reject `limit`/`offset` (HTTP 400).**
+  `GET /record/v1/{type}/{id}/{sublist}` (e.g. `.../itemFulfillment/{id}/item?limit=1000&offset=N`)
+  returns **400 `INVALID_PARAMETER`** — *"Use one of: fields, expand, expandRecords,
+  expandSubResources, simpleEnumFormat, ids"*. `limit`/`offset` are valid only on **collection**
+  endpoints, not on a record's sublist. A shim that paginated a sublist this way silently got
+  **0 lines** and imported the record **header-only** with no error. Fetch line data via **SuiteQL
+  `transactionline`** instead (the pattern every other shim in `rest.php` already uses). Surfaced
+  when `fetchItemFulfillmentById` returned zero lines — see
+  [NYCHH inventory-adjustment → item-fulfillment linking](../../../clients/nychh/features/netsuite-inventory-adjustment-fulfillment-link.md).
+
+### `fetch*ById()` single-record helpers — the REST replacements for the SOAP `App_NetSuite::get*`
+
+The togasupply importer fetches individual records by internal id through a family of `fetch*ById()`
+helpers on `App_Api_Netsuite_Rest`, each assembling a SOAP-shaped shim from a SuiteQL header/lines
+query plus (where needed) a REST record GET. As of **2026-08-29 the togasupply sync path uses these
+exclusively — zero `App_NetSuite::` SOAP network calls remain** in `common_sync_togasupply.php` or the
+`*FromNetsuite()` methods:
+
+- **`fetchItemReceiptById`** — header + lines + serials (serials via SuiteQL
+  `inventoryassignment ⋈ inventorynumber`, grouped per product). Replaces SOAP
+  `getItemReceipt`/`getInventoryNumber*`/`getItemIsSerialized`.
+- **`fetchPurchaseOrderById`** / **`fetchSalesOrderByIdFull`** — replace SOAP `getPurchaseOrder` /
+  `getSalesOrder`.
+- **`fetchItemFlagsByIds`** — batch item serialized/fulfillable flags; replaces
+  `getItemSerializedAndFulfillable`.
+- **`fetchInventoryAdjustmentById`** — replaces the `diagnose_hh` script's SOAP `getObject`.
+- **`fetchInvoiceFile`** — SuiteQL `file`-table lookup + REST `GET /record/v1/file/{id}` content,
+  `base64_decode` → raw bytes. Replaces SOAP `getInvoiceFile`.
+
+`listCustomers()` also gained a **`companyName`** field on its shim (the `netsuite_customers.php` cron
+moved from `listAllCustomers` → `listCustomers`). REST-shim *shape* traps that bite these helpers (an
+absent nested list crashes 1.0; `scriptId` case-sensitivity on `customFieldList`) are in
+[`netsuite-suiteql-rest-shim.md`](netsuite-suiteql-rest-shim.md).
 
 ## `list*()` helpers — behavior & cost
 
@@ -392,6 +442,24 @@ numbers. Budget hours for multi-year runs and launch them under `nohup`/`tmux`.
 
 ## Change history
 
+- 2026-08-29 — Documented the **`fetch*ById()` single-record helper family** (`fetchItemReceiptById`,
+  `fetchPurchaseOrderById`, `fetchSalesOrderByIdFull`, `fetchItemFlagsByIds`,
+  `fetchInventoryAdjustmentById`, `fetchInvoiceFile`) that replaced the SOAP `App_NetSuite::get*` calls,
+  and the `listCustomers` `companyName` addition — the togasupply sync path now makes **zero
+  `App_NetSuite::` SOAP network calls**. Added while root-causing the 5 stuck togasupply integrations as
+  REST-shim shape mismatches (see the
+  [per-client-sync doc](../../worker/features/netsuite-togasupply-per-client-sync.md)). (jcardinal)
+- 2026-08-29 — Recorded two NetSuite REST/SuiteQL facts from the NYCHH inventory-adjustment →
+  item-fulfillment **REST migration**: **REST record sublist endpoints
+  (`/record/v1/{type}/{id}/{sublist}`) reject `limit`/`offset` with a 400 `INVALID_PARAMETER`** (a
+  paginated sublist fetch silently returns 0 lines → header-only import; use SuiteQL
+  `transactionline`), and an **Item Fulfillment (`ItemShip`) `transactionline` returns ~3 rows per
+  fulfilled item** (order-linked + positive "wash" + `isinventoryaffecting='T'`) — keep only the line
+  with a `previoustransactionlinelink` of type `SalesOrd`/`TrnfrOrd` and derive `orderLine` from its
+  `previousline`; **`mainline='F'` is the wrong filter** because NetSuite sometimes marks the first
+  real line `mainline='T'`. See
+  [NYCHH inventory-adjustment → item-fulfillment linking](../../../clients/nychh/features/netsuite-inventory-adjustment-fulfillment-link.md).
+  (jcardinal)
 - 2026-08-19 — Added two SuiteQL mechanics that fail **silently**, both found porting the customer
   account-type sync (TRUE-80206): **column aliases come back lower-cased** (`AS accountTypeLabel` →
   `accounttypelabel`, so a camelCase read is `NULL` with no error — it made a backfill report success while

package/knowledge/1.0/apps/library/features/netsuite-suiteql-rest-shim.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-27
+updated: 2026-08-29
 owners: [dfranks, jcardinal, kyalamarthi]
 files:
   - library/app/api/netsuite/rest.php
@@ -112,6 +112,29 @@ Forecast2 tables already store.
   TransferOrders). A custom field absent from the record reads as null downstream. See
   [NYCHH NetSuite → TransferOrders import](../../../clients/nychh/features/netsuite-transfer-order-import.md).
 
+- **⚠ `scriptId` in a `customFieldList` def is CASE-SENSITIVE on lookup — a case skew silently
+  returns the default (2026-08-29).** `custbody_stocking_order` was **tagged** in the shim with the
+  uppercase scriptId `CUSTBODY_STOCKING_ORDER` but **read** by the importer as lowercase
+  `custbody_stocking_order`, so the lookup never matched and always fell back to the default (unchecked)
+  — which mis-routed **every** NYCHH order to a Transfer Order. Fixed by lowercasing the scriptId in
+  **both** `buildSalesOrderShims()` and `fetchSalesOrderById()` defs; `END_CUSTOMER` is intentionally
+  left uppercase because it is resolved by internalId `3149`, not by scriptId. Nothing errors on a case
+  skew — the field just reads as its default — so verify the exact scriptId string on both the write and
+  the read side. See [NYCHH TransferOrders import](../../../clients/nychh/features/netsuite-transfer-order-import.md).
+
+- **A shim must produce the SOAP object's SHAPE, not just its scalar fields — an absent nested list
+  crashes 1.0 (2026-08-29).** `fetchCustomerById()`'s `addressbookList` was where the AIG lookup phase
+  crashed: a REST customer with no/odd address made the shim omit the nested `addressbook` structure the
+  old SOAP object always carried, and the downstream unguarded read raised a warning → `App_Error`
+  `exit()` (see the `getCustomFieldValue` warning-safety gotcha below — same class). It now builds
+  `addressbookList` via a `shimAddress()` helper that normalizes `country` to the `_unitedStates` enum
+  and returns an **empty `addressbook: []`** when there is no address, so the shape always matches;
+  two helpers were extracted for reuse — `countryToSoapEnum()` (country string → SOAP enum) and
+  `refString()`. This is the concrete "REST shim returns null/absent where SOAP had a value" failure
+  the [per-client-sync doc](../../worker/features/netsuite-togasupply-per-client-sync.md) diagnoses via
+  `Logs.Issue`/`Logs.Event`. **When adding or editing a shim, reproduce the full SOAP shape (including
+  empty nested lists), not just the fields you happen to need.**
+
 ## Transaction status sourcing (1.0) — and the 2026.2 REST `status.id` change
 
 1.0 reaches NetSuite over **two transports, and neither reads status off a REST record GET
@@ -192,6 +215,17 @@ None — uniform across clients (NetSuite is a single shared account).
 
 ## Change history
 
+- 2026-08-29 — Recorded two shim-shape facts from root-causing the 5 stuck togasupply integrations
+  (which were **shim-shape mismatches, not dead SOAP** — see the
+  [per-client-sync doc](../../worker/features/netsuite-togasupply-per-client-sync.md)): a
+  `customFieldList` **`scriptId` is case-sensitive on lookup** — `CUSTBODY_STOCKING_ORDER` (write) vs
+  `custbody_stocking_order` (read) silently returned the default and mis-routed every NYCHH order to a
+  Transfer Order (fixed by lowercasing in both `buildSalesOrderShims`/`fetchSalesOrderById`;
+  `END_CUSTOMER` stays uppercase, resolved by internalId 3149); and a shim must reproduce the SOAP
+  object's **full shape** — `fetchCustomerById()`'s `addressbookList` omitting the nested `addressbook`
+  crashed the AIG lookup phase (unguarded null read → warning → `exit()`), now built via `shimAddress()`
+  (country → `_unitedStates` enum, empty → `addressbook: []`) with extracted `countryToSoapEnum()` /
+  `refString()` helpers. (jcardinal)
 - 2026-08-27 — **Traced the missing `tl.location` SELECT to its cause — a merge, not an omission — and
   recorded what restoring it re-animates** (forecast2 open-orders, TRUE-79162). TRUE-79078 (31fadd77)
   originally added `tl.location` + `BUILTIN.DF(tl.location)`; merge c3caa11a (2026-06-24) resolved in

package/knowledge/1.0/apps/library/features/toga2-api-client-and-bridge.md

@@ -6,7 +6,7 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-17
+updated: 2026-08-29
 owners: [jcardinal, mhammontree, bala]
 files:
   - library/app/api/toga2.php
@@ -396,6 +396,15 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
 
 ## Change history
 
+- 2026-08-29 — The `*FromNetsuite()` importer methods in this class were **completed onto REST** — the
+  item-receipt and inventory-adjustment paths dropped their last `App_NetSuite::` SOAP calls in favor of
+  `App_Api_Netsuite_Rest::fetch*ById()`, so the togasupply importer now makes **zero SOAP network
+  calls**. Also **corrects the 2026-08-27 entry below**: the private `isStockingOrder()` custom-field
+  read had a `scriptId` case-mismatch (`CUSTBODY_STOCKING_ORDER` vs `custbody_stocking_order`) that
+  silently defaulted and mis-routed every NYCHH order — now fixed. Method-level detail and the full
+  per-client fix set live on
+  [NetSuite → TOGa Supply per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md)
+  (2026-08-29). (jcardinal)
 - 2026-08-27 — `send()`'s throw sites were **reverted to plain `throw new Exception(...)`** (both
   sites) as part of removing the sync engine's swallow-and-skip data-loss bug — the importer must
   propagate a failed write, not catch it (see

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-08-28
+updated: 2026-08-29
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -520,8 +520,117 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
   item-fulfillment lookup set through for the on-demand fulfillment import (lookups are passed
   function-to-function, like the other sync functions).
 
+- **⚠ Inventory-adjustment sync migrated SOAP → REST + now fails LOUD (2026-08-29).** The SOAP path
+  flagged just above (`App_NetSuite::getInventoryNumber*`, ~2 round-trips per serial) has been
+  **migrated to REST/SuiteQL** via `App_Api_Netsuite_Rest`, and the **on-demand fulfillment /
+  sales-order import** it triggers was converted to REST too — closing the ~1h-per-large-adjustment
+  cost that was the previously-planned next step. Also, the remaining **error-log-and-swallow
+  `try/catch` blocks in the NetSuite→DB sync path were removed** so a data-corruption failure surfaces
+  loudly (StarTech/Sentry catches left alone) — the same loud-failure policy as the 2026-08-27
+  per-order `try/catch` removal. Full detail (the REST-shim fixes it required, and the bridges →
+  direct-FK-column change) on
+  [NYCHH inventory-adjustment → item-fulfillment linking](../../../clients/nychh/features/netsuite-inventory-adjustment-fulfillment-link.md).
+
+- **⚠ 2026-08-29: the 5 stuck togasupply integrations were REST-shim SHAPE mismatches, NOT dead
+  SOAP — and how to tell them apart.** Five clients had a section frozen at `RUNNING` and the first
+  hypothesis was "SOAP is down." **SOAP was up.** The real cause was introduced by the earlier
+  SOAP→REST list-method conversion: a REST shim returns `null`/absent where the old SOAP object
+  carried a value, and in 1.0 **any unguarded read of that null raises a PHP warning that
+  `App_Error` escalates to `exit()`** (see the 1.0 backend-php standard *Any PHP warning terminates
+  the request*, and the [rest-shim warning-safety gotcha](../../library/features/netsuite-suiteql-rest-shim.md)).
+  The `exit()` mid-section leaves that record-type's `NETSUITE_EXECUTION_MODE_*` stuck at `RUNNING`
+  with the watermark frozen — i.e. **a shim-shape mismatch presents identically to a poison order.**
+  So a stuck section is never "SOAP is dead"; it is one specific record hitting one specific
+  unguarded shim field.
+  **Diagnosis playbook (durable):** query prod **`Logs.Issue` + `Logs.Event`** (the
+  `App_Error_Capture` tables, schema `Logs`, via the toga-db MCP) for the client's `clientId` — each
+  stuck section maps to an exact crash **file:line** in `common_sync_togasupply.php` or `toga2.php`.
+  The `RUNNING` mode + frozen watermark **is** the stuck signal (see the window/watermark gotchas
+  above); `Logs.Issue`/`Event` turns it into a line number, far faster than reading the cron blind.
+  **Per-client fixes shipped (all in `library`, `php -l` clean, and fail-loud — a genuinely
+  unresolvable case now throws rather than silently continuing):**
+  - **Item receipts — Canon + Endeavor Health** (`syncItemReceiptFromNetsuite`): migrated off SOAP to
+    new REST `fetchItemReceiptById` (header + lines + serials via SuiteQL
+    `inventoryassignment ⋈ inventorynumber`, serials grouped per product) + `fetchPurchaseOrderById`
+    + `fetchItemFlagsByIds`; removed all `App_NetSuite::` SOAP calls (`getItemReceipt` /
+    `getPurchaseOrder` / `getItemIsSerialized` / `getInventoryNumber*`). Guards added;
+    **`RtnAuth` (return-authorization) item receipts are intentionally NOT imported** (explicit
+    documented skip), and an **unknown `createdFrom` type throws**.
+  - **Purchase orders** (`syncPurchaseOrderFromNetsuite`): a missing PO entity now **throws** (was an
+    unguarded crash); `getSalesOrder` → REST `fetchSalesOrderByIdFull`; a `2400` ACL-strip that used
+    to skip now **throws**. Threaded a new `array &$lookupWarehouseByNetsuiteLocationInternalId` param
+    from **both** callers — which also fixed a **null `arg13` `TypeError`** into
+    `syncSalesOrderFromNetsuite`.
+  - **Transfer orders — GroWrk `SALES_ORDERS`** (`syncTransferOrderFromNetsuite`): fixed an
+    all-catalog lookup that read `->uuid` off the array instead of `[0]`; an **unmapped NetSuite TO
+    status now throws** (was default-to-pending + log).
+  - **Item fulfillments — Elite (also Quad / S&P Global / Prudential-EDI)**
+    (`syncItemFulfillmentFromNetsuite`): the "Undefined index" on service/shipping lines with an
+    **empty `orderLine`** (`$lookupNsSalesOrderItemsByOrderLine['']`) is now guarded so it falls
+    through to the existing reconstruct path.
+  - **NYCHH stocking-order routing** — the `isStockingOrder` scriptId **case-mismatch** (full detail
+    in the [rest-shim doc](../../library/features/netsuite-suiteql-rest-shim.md)): the custom field was
+    tagged `CUSTBODY_STOCKING_ORDER` but looked up lowercase → always returned the default →
+    **every NYCHH order was mis-routed to a Transfer Order.** Fixed by lowercasing the scriptId in
+    both shim defs.
+  - **AIG lookup-phase crash** — `fetchCustomerById`'s `addressbookList` is now built via `shimAddress`
+    (country normalized to the `_unitedStates` enum, empty → `addressbook: []`); extracted
+    `countryToSoapEnum()` + `refString()` helpers, plus a belt-and-suspenders guard in
+    `common_sync_togasupply.php`.
+
+- **SOAP→REST is now COMPLETE for the togasupply sync path (2026-08-29).** With the item-receipt and
+  (2026-08-29) inventory-adjustment migrations plus the new `fetch*ById` methods, **zero
+  `App_NetSuite::` (SOAP) network calls remain** anywhere in the `common_sync_togasupply.php` engine
+  or the `*FromNetsuite()` methods it calls — so the whole tier-wide-freeze class above is now driven
+  by REST-shim shape, not SOAP availability. New REST completeness pieces built in `library`:
+  `fetchInvoiceFile` (SuiteQL `file` lookup + REST `GET /record/v1/file/{id}` content, `base64_decode`
+  → raw bytes; replaces `getInvoiceFile`), `getItemSerializedAndFulfillable` → `fetchItemFlagsByIds`,
+  the `diagnose_hh` script's `getObject` → `fetchInventoryAdjustmentById`, and
+  `worker/crons/sync/netsuite/netsuite_customers.php` `listAllCustomers` → `listCustomers` (with
+  `companyName` added to the `listCustomers` shim).
+
+- **⚠ SALES_ORDERS line renumber is now a validate-before-mutate TWO-PHASE UPDATE (2026-08-29) —
+  supersedes the delete-recreate + pinned-skip approach.** `syncSalesOrderFromNetsuite`'s renumber no
+  longer DELETEs and re-creates lines (nor keeps un-deletable/invoiced rows at their old number — see
+  the 2026-08-17 pinned-skip gotcha above, now historical). It **parks** every drifting line at a
+  temporary `lineNumber` (base = `max(current, target lineNumbers) + headroom`, headroom const
+  **1000**), then **finalizes** each to its target — so `UNIQUE(salesOrderId, lineNumber)` is never
+  transiently violated and pinned FK-RESTRICT children (invoiced/fulfilled lines) renumber accurately
+  via `UPDATE` instead of being stranded at a stale number. It **throws BEFORE any PUT** if a kept or
+  undeletable row occupies a needed target, so a failure never leaves the order in a partial state.
+  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).
+
 ## Change history
 
+- 2026-08-29 — **Root-caused the 5 stuck togasupply integrations as REST-shim SHAPE mismatches, not
+  dead SOAP, and fixed them.** SOAP was up; the earlier SOAP→REST conversion left shims returning
+  null/absent where SOAP had values, and a 1.0 unguarded read of that null → PHP warning →
+  `App_Error` `exit()` → the section frozen at `RUNNING`/watermark stuck (presents identically to a
+  poison order). Recorded the durable diagnosis playbook (map each stuck `clientId`/section to a crash
+  file:line via prod `Logs.Issue`/`Logs.Event`, the `App_Error_Capture` tables). Shipped per-client
+  `library` fixes, all fail-loud: item-receipts SOAP→REST (`fetchItemReceiptById` +
+  `fetchPurchaseOrderById` + `fetchItemFlagsByIds`, RtnAuth skip, unknown `createdFrom` throws — Canon
+  + Endeavor Health); PO missing-entity throw + `arg13` warehouse-lookup TypeError fix +
+  `fetchSalesOrderByIdFull` + 2400-ACL throw; TransferOrder all-catalog `[0]`/`->uuid` fix + unmapped
+  status throw (GroWrk); IF empty-`orderLine` "Undefined index" guard (Elite/Quad/S&P/Prudential-EDI);
+  the `isStockingOrder` scriptId case-mismatch that mis-routed **every** NYCHH order to a Transfer
+  Order; and the AIG `fetchCustomerById` address-shim crash. Also **completed SOAP→REST for the whole
+  togasupply path** (zero `App_NetSuite::` network calls remain; new `fetchInvoiceFile` /
+  `fetchItemFlagsByIds` / `fetchInventoryAdjustmentById`, `listAllCustomers`→`listCustomers`+companyName),
+  and replaced the SALES_ORDERS renumber with a **validate-before-mutate two-phase UPDATE** (park at
+  temp lineNumbers, then finalize; throws before any PUT) superseding the delete-recreate + pinned-skip
+  approach. (jcardinal)
+- 2026-08-29 — The inventory-adjustment sync (and the on-demand fulfillment / sales-order import it
+  triggers) in `syncInventoryAdjustmentFromNetsuite` was **migrated SOAP → REST/SuiteQL**, closing the
+  SOAP round-trip cost flagged 2026-08-28; the remaining error-log-and-swallow `try/catch` in the
+  NetSuite→DB sync path were removed for loud failure (StarTech/Sentry catches untouched). The
+  migration required two `App_Api_Netsuite_Rest` shim fixes (a record-sublist `limit`/`offset` 400 and
+  the ItemShip 3-rows-per-item line filter) and moved the NYCHH adjustment↔fulfillment link off bridge
+  tables onto direct FK columns — see
+  [NYCHH inventory-adjustment → item-fulfillment linking](../../../clients/nychh/features/netsuite-inventory-adjustment-fulfillment-link.md).
+  (jcardinal)
+
 - 2026-08-28 — Recorded two shared-engine inventory-adjustment fixes in
   `syncInventoryAdjustmentFromNetsuite` (prune child `InventoryAdjustmentItemUnits` before the item —
   FK RESTRICT/1451/EV-11; index the item lookup **one-level** `[$partNumber]` to match what the cron

package/knowledge/1.0/standards/backend-php.md

@@ -5,13 +5,14 @@ project: Library
 client: shared
 type: standard
 status: active
-updated: 2026-08-21
+updated: 2026-08-29
 owners: [jcardinal, rgirish, mhammontree, ajean]
 files: []
 related:
   - ../apps/library/architecture.md
   - ../apps/library/features/email-queue-attachments.md
   - ../apps/library/features/error-capture-1-0.md
+  - ../apps/worker/features/netsuite-togasupply-per-client-sync.md
   - ../../2.0/standards/backend-php.md
 ---
 
@@ -507,9 +508,12 @@ Additional verified detail:
 - **Diagnostic fingerprint:** an occurrence count that is an exact multiple of the job's
   scheduled frequency (e.g. 20/hour for `*/3 * * * *`) means **one** poisoned item retried,
   not many distinct failures.
-- **In job code, prevention beats containment.** Guard optional data with `isset()` before
-  reading it, and consume/ack the item in a `finally` (or under a `catch (Throwable)`) so a
-  genuine exception cannot strand it. You cannot wrap your way out of a notice.
+- **In job code, prevention beats containment for a warning.** Guard optional data with
+  `isset()` before reading it — you cannot wrap your way out of a notice. This is about the
+  uncatchable-warning mechanics above; it is **not** license to ack-and-continue past a genuine
+  (catchable) exception in a reconciliation loop. See *Fail-loud is the default for
+  import/sync/cron code* below before reaching for a `finally`/`catch (Throwable)` ack — that
+  pattern caused a real data-loss incident in this exact engine.
 
 > **Existing guidance under review.** An earlier version of this section recommended
 > wrapping fragile I/O in `try { ... } catch (\ErrorException $e)` relying on the GLOBAL
@@ -521,6 +525,59 @@ Additional verified detail:
 > (~L112-123), `clients/prudential/profile.md` (~L75). Prefer the local-handler pattern
 > from the canonical section above for anything new.
 
+### Fail-loud is the default for import/sync/cron code — never catch-and-continue or log-and-skip a record
+
+**This is the standing policy for reconciliation jobs; it supersedes the "consume/ack in a
+`finally`" framing in the section above wherever the two would conflict.** For import/sync/cron
+code that reconciles data from an external system into ours — the NetSuite → TOGa Supply sync
+(`worker/crons/toga2/netsuite/`) is the canonical example — the rule is: **if anything prevents
+the job from producing accurate data, let it throw.** The exception must propagate and abort the
+run. Do not:
+
+- Wrap a per-record dispatch in `try { … } catch (Throwable) { error_log(...) }` and move on to
+  the next record.
+- Wrap a section/job in `try { … } finally { <advance the checkpoint> }` so the checkpoint still
+  moves even when the try body threw.
+- Downgrade a hard failure to a log line and keep going "because most records succeeded."
+
+**Why.** These jobs track progress with an execution-mode flag plus a watermark/cursor (e.g.
+`NETSUITE_EXECUTION_MODE_*` / `NETSUITE_LAST_SYNC_DATETIME_*`). A thrown, unhandled exception
+leaves that state at **RUNNING** with the watermark **not advanced** past the failure — visible
+proof the run failed, the record still owes a retry, and a developer needs to look. Catching the
+exception and continuing does the opposite: it drops the record, silently advances the checkpoint
+past it (the loss becomes **permanent**, not retried), and can even reset the mode back to
+**IDLE**, telling the next run "everything's fine" when it isn't. **Data accuracy is prioritized
+over availability here — even for a failure that is not auto-retriable** (an ACL/permission
+error, a malformed upstream record, a constraint violation). A run stuck at RUNNING that needs a
+developer to reconcile it is the correct, intended outcome; a clean-looking IDLE run that quietly
+dropped data is not.
+
+**The one legitimate exception is a true message/inbox queue** — a loop reading items one at a
+time from something like an IMAP inbox or an SQS queue, where an item that is never acknowledged
+blocks every item behind it forever. There, and only there, consuming/acking the poison item so
+the queue can move past it is defensible — and even then, **prefer surfacing** the failure
+(dead-letter it, alert on it, record it against the item) over silently discarding it. A
+reconciliation cron with its own per-client cursor is **not** this case: nothing blocks behind a
+RUNNING watermark except that one client's own next run, which is exactly what the window
+grow/shrink behavior is designed around.
+
+**Real incident.** On 2026-08-20 a change wrapped every per-order dispatch across all six
+NetSuite → TOGa Supply sections in `catch (Throwable) { error_log }` and wrapped each section in
+`try { … } finally { finishModeIteration }`. It looked like an improvement — "don't let one bad
+order jam the sync" — but it silently dropped any record whose write failed, advanced the
+watermark past it, and reset the mode to IDLE, so a failed run looked identical to a successful
+one. This was found and reverted 2026-08-27 (all per-order catches and section-level
+`try/finally` removed — a failure now aborts the section with the mode left RUNNING), and a
+related error-log-and-swallow path in the same engine's inventory-adjustment section was removed
+again 2026-08-29 during its SOAP→REST migration. Full detail: [NetSuite → TOGa Supply Per-Client
+Sync](../apps/worker/features/netsuite-togasupply-per-client-sync.md).
+
+This does not relax the "any PHP warning terminates the request" mechanics above, or the two
+sanctioned local opt-outs for a **notice/warning** you must genuinely contain (a monitoring ping,
+a defensively-guarded optional read). Those exist to survive an *uncatchable warning* without
+crashing something that must not crash. This rule is about a **catchable exception** in a
+reconciliation loop, where surviving it quietly is exactly the wrong behavior.
+
 ### Test mode silently disables queued email — non-prod cannot validate a queue bug
 
 `App_Email::setQueueForSending()` (`library/app/email.php` ~L161) is gated on

package/knowledge/1.0/standards/framework-rules.md

@@ -5,12 +5,13 @@ project: Library
 client: shared
 type: standard
 status: active
-updated: 2026-08-06
+updated: 2026-08-29
 owners: [jcardinal, ajean]
 files: []
 related:
   - ../apps/library/architecture.md
   - ../apps/worker/architecture.md
+  - backend-php.md
 ---
 
 # Framework 1.0 (App_) Rules
@@ -150,3 +151,12 @@ public function processOrder(): void {
     $this->response->success($result);
 }
 ```
+
+**This pattern is scoped to a single request/response unit of work — it does not extend to
+import/sync/cron code.** Above, catching stops the *whole* action and returns one error response;
+nothing after the catch runs "successfully" on partial data. A batch/reconciliation job (a cron
+looping over many external records, advancing a cursor/watermark) is a different shape: catching
+per-record there and continuing to the next one is exactly the anti-pattern that caused a
+data-loss incident in the NetSuite → TOGa Supply sync. For that class of code, see
+`1.0/standards/backend-php.md` § *Fail-loud is the default for import/sync/cron code* — the job
+must throw and abort, not catch-and-continue.

package/knowledge/2.0/apps/api2/features/request-logging.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
-owners: ["mhammontree", "dfranks", "bala"]
+updated: 2026-08-29
+owners: ["mhammontree", "dfranks", "bala", "jcardinal"]
 files:
   - api2/Component/Api/V2/V2.php
   - api2/Controller/Index.php
@@ -175,6 +175,14 @@ There is no usable index on those columns. Do not start from a payload search.
 
 The working pattern, in order:
 
+> **`route` values are stored WITH the `/v2` prefix** (e.g. `/v2/inventory-adjustments/{uuid}`,
+> `/v2/item-fulfillment-items`), so any narrowing predicate must filter `route LIKE '/v2/...'` — a
+> bare `/inventory-adjustments` matches **nothing**. `route` also carries `requestPayload` +
+> `responsePayload` + `responseCode` per row, so once narrowed the log gives the full request/response
+> for a call **without NetSuite access** — it was the decisive tool for confirming a V2 PUT persisted
+> a field its response echo omitted (see the [V2 query contract](v2-rest-query-contract.md) PUT-echo
+> gotcha).
+
 1. **Narrow with indexed / non-text columns only** — a `dtStamp` range plus `route`,
    `method`, `responseCode`, `hostname`. A
    `GROUP BY hostname, route, method, responseCode` over one day is cheap and is the fastest way
@@ -217,6 +225,12 @@ re-send.
 
 ## Change history
 
+- 2026-08-29 — Noted that `Logs.Api.route` values are stored **with the `/v2` prefix** (e.g.
+  `/v2/inventory-adjustments/{uuid}`), so narrowing queries must filter `route LIKE '/v2/...'` — a
+  bare `/inventory-adjustments` predicate matches nothing. Reinforced that a narrowed row's
+  `requestPayload`/`responsePayload` is the decisive, NetSuite-access-free tool for diagnosing V2
+  write behavior — here, confirming a V2 PUT persisted a field its response echo omitted (NYCHH
+  inventory-adjustment → item-fulfillment linking). (jcardinal)
 - 2026-08-13 — **Important limit on the "an HTTP 400 leaves a full log row" rule** (TRUE-80412):
   `execute()` writes the transaction log near its **end** (~L2225-2271), *after* route processing
   (~L1742-2043), so **a throw from a PRE interceptor produces no `Logs.Api` row at all** — the

package/knowledge/2.0/apps/api2/features/v2-rest-query-contract.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
-owners: [tcox, bala, apeterson]
+updated: 2026-08-29
+owners: [tcox, bala, apeterson, jcardinal]
 files:
   - api2/Component/Api/V2/V2.php
 related:
@@ -108,6 +108,19 @@ calculated field is null on a nested object but correct when that object is fetc
 Definition of the fields themselves:
 [FIELD_SQL calculated fields](../../_underscore/features/calculated-sql-fields.md).
 
+### ⚠ A non-null FK object at the MAX requested `depth` is OMITTED from the response
+
+A GET serialized to `depth: N` renders FK objects down to level N, but a **non-null FK object that
+sits at level N+1** — one hop *past* the max — is **dropped from the payload with no error**. It is
+easy to miss because a **null** sibling FK still renders as `null`, so the omission reads like "that
+FK is null" rather than "that FK was not serialized." Observed on `GET /item-fulfillment-items` at
+`depth: 2`: the grandchild `item` (level 3 — `itemFulfillmentItem → salesOrderItem → item`) was
+absent, so a product-match keyed on `salesOrderItem.item.uuid` came back empty and no link was
+written. **Fix: request `depth: N+1`, or name the nested path explicitly in `fields`** (e.g.
+`salesOrderItem.item.uuid` / `transferOrderItem.item.uuid`). Rule of thumb: the deepest FK you
+actually read must sit at least one level *inside* `depth`, not on the boundary. Surfaced building
+[NYCHH inventory-adjustment → item-fulfillment linking](../../../../clients/nychh/features/netsuite-inventory-adjustment-fulfillment-link.md).
+
 ### What nests by default is `InherentRecordChildren` — everything else needs the nested ROUTE
 
 A record's one-to-many children arrive inside the record response **only** if `Core.
@@ -271,8 +284,24 @@ where=(field:op:value,LOGIC,field:op:value,(nested,OR,nested))
 - **`gte`/`lte` silently are not operators** — use `ge`/`le`.
 - **Do not trust a 200 with missing fields.** Without an explicit `fields=` list, ACL removal is
   invisible; re-request with `fields=` to force `EZ-2` and see the denied list.
+- **⚠ A PUT response ECHO can omit a field that DID persist — verify against the DB, not the echo.**
+  A `PUT /v2/inventory-adjustments/{uuid}` with `{"itemFulfillment":{"uuid":…}}` returned **200 with
+  an empty `messages[]`** and an echo that did **not** contain `itemFulfillment`, yet the FK column
+  **persisted correctly**. An absent field in the write-response echo is **not** proof the write
+  failed — confirm the field against the record's DB row (or the `Logs_<Client>.Api` `responsePayload`),
+  never from the write's own echoed body. See
+  [V2 request logging](request-logging.md).
 
 ## Change history
+- 2026-08-29 — Recorded two response-shape facts from the NYCHH inventory-adjustment REST work: **a
+  non-null FK object one hop past the max `depth` is silently omitted** (a null sibling FK still
+  renders, so it reads as "null" not "missing") — `GET /item-fulfillment-items` at `depth:2` dropped
+  the level-3 `salesOrderItem.item`; fix with `depth+1` or an explicit nested `fields` path — and a
+  **PUT response echo can omit a field that persisted** (a `PUT /v2/inventory-adjustments/{uuid}`
+  returned 200 / empty-`messages` without echoing `itemFulfillment` though the FK saved), so verify a
+  write against the DB / `Logs_<Client>.Api`, not the echo. See
+  [NYCHH inventory-adjustment → item-fulfillment linking](../../../../clients/nychh/features/netsuite-inventory-adjustment-fulfillment-link.md).
+  (jcardinal)
 - 2026-08-28 — Documented two response-shape facts hit while building the Transfer Orders modal.
   **`calcDepth` defaults to 1**, so a `FIELD_SQL` calculated field on a record one FK hop out returns
   `null` with **no** message (Location's `_address*` fields needed `calcDepth: 2`) — raise it one per

package/knowledge/2.0/standards/backend-php.md

@@ -5,13 +5,15 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-08-25
+updated: 2026-08-29
 owners: [jcardinal, mhammontree, dfranks, bala]
 files: []
 related:
   - ../apps/_underscore/architecture.md
   - ../apps/api2/architecture.md
   - ../apps/worker2/architecture.md
+  - framework-rules.md
+  - ../../1.0/standards/backend-php.md
 ---
 
 ## General Principals
@@ -677,6 +679,14 @@ $c = 'Hello ' . $world;
 ### PHP Error Handling
 
 * Always use exceptions to handle unexpected conditions.
+* **Import/sync/cron code that reconciles external data must fail loud — never catch-and-continue
+  or log-and-skip a record.** A mid-loop failure must throw and abort the job, leaving its
+  checkpoint/watermark unmoved for retry/investigation, rather than being caught, logged, and
+  stepped over. See `2.0/standards/framework-rules.md` § *The above is for a per-entity job — a
+  reconciliation/import worker that loops over many records is different, and must fail loud* and
+  `1.0/standards/backend-php.md` § *Fail-loud is the default for import/sync/cron code* (the
+  policy this corrects, after a per-order catch-and-continue change caused a data-loss incident in
+  the NetSuite → TOGa Supply sync).
 
 ### Choosing an exception class is a ROUTING decision, not style
 
@@ -946,6 +956,10 @@ See: 2.0/apps/worker2/features/cross-account-aws-access.md
 
 ## Change history
 
+- 2026-08-29 — Added a fail-loud cross-reference under **PHP Error Handling**: import/sync/cron
+  code that reconciles external data must never catch-and-continue or log-and-skip a record;
+  points to the full policy and the NetSuite → TOGa Supply sync data-loss incident recorded in
+  `framework-rules.md` and `1.0/standards/backend-php.md`. (jcardinal)
 - 2026-08-25 — Clarified the exception-routing rule: `_Exception_Validation` is a valid 400 throw
   site from a **scripted-API method** too, not only a pre/post interceptor or model op. Verified at
   the outer `execute()`/`api()` catch in `api2/Controller/Index.php` (~L317) where

package/knowledge/2.0/standards/framework-rules.md

@@ -5,7 +5,7 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-08-28
+updated: 2026-08-29
 owners: [jcardinal, ajean, apeterson]
 files: []
 related:
@@ -14,6 +14,8 @@ related:
   - ../apps/api2/architecture.md
   - ../apps/dbchanges2/architecture.md
   - ../apps/dbchanges2/features/surface-layer-schema.md
+  - backend-php.md
+  - ../../1.0/standards/backend-php.md
 ---
 
 # Framework 2.0 (_underscore) Rules
@@ -298,6 +300,23 @@ returns nothing (or returns only when it succeeds) leaves a blind spot in the au
 only for genuinely retriable conditions, where the queue's retry is the intended behaviour; a
 handled non-retriable failure should return a result describing what happened rather than throwing.
 
+### The above is for a per-entity job — a reconciliation/import worker that loops over many records is different, and must fail loud
+
+`ProcessOrder(int $orderId)` above is scoped to **one** record: the job either succeeds or fails
+as a whole, and "log and return a failure result" for a non-retriable error means *this job*
+(this one order) is done — no other record is silently dropped alongside it. Do not generalize
+that shape to a worker action that **internally loops over many records to reconcile external
+data** (a NetSuite import, a bulk sync, anything advancing its own cursor/watermark across a
+batch). For that shape, catching a per-record failure inside the loop and moving on to the next
+record is the same anti-pattern documented in `1.0/standards/backend-php.md` § *Fail-loud is the
+default for import/sync/cron code* — it silently drops the record and can leave the job's own
+progress-tracking (checkpoint/cursor) looking healthy when it isn't. A batch/reconciliation worker
+must let a mid-loop failure **throw and abort the job**, leaving its checkpoint unmoved so the
+queue's retry (or a developer) picks up where it actually left off — never catch-per-record and
+continue. Data accuracy outranks job "completion," even when the failure is not retriable (e.g. an
+ACL error on one record) — a developer reconciling a stalled job is the intended outcome, not a
+job that reports success having quietly skipped records.
+
 ## `c_`-prefixed custom columns are framework-dynamic
 
 Columns prefixed `c_` are **custom/dynamic** columns that the `_underscore` model layer handles
@@ -317,6 +336,14 @@ and not how the convention works. Use a non-`c_` column when you *do* want the f
 ACL-governed field treatment.
 
 ## Change history
+- 2026-08-29 — Added a distinction under **Error handling in workers**: the documented
+  `ProcessOrder`-style per-entity pattern (catch non-retriable, log, return a failure result) does
+  **not** extend to a worker action that loops over many records to reconcile external data (a
+  NetSuite import, a bulk sync). That shape must fail loud — a mid-loop failure throws and aborts
+  the job so its checkpoint/cursor stays unmoved — matching the fail-loud policy corrected in
+  `1.0/standards/backend-php.md` after a per-order catch-and-continue change caused a silent
+  data-loss incident in the NetSuite → TOGa Supply sync (found 2026-08-20, reverted 2026-08-27,
+  final swallow removed 2026-08-29). (jcardinal)
 - 2026-08-28 — Extended § Schema migrations with the production-state rules. Recorded that cluster
   isolation is **physical** (verified: the prod Core reader exposes only Core/Forecast/
   Forecast_Archive/Team, the client reader only `Client_*`), so a cross-database reference cannot

package/knowledge/INDEX.md

@@ -46,9 +46,11 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## Clients
 
 - **AIG (Staples Protection Plan)** (`aig`) → [clients/aig/INDEX.md](clients/aig/INDEX.md)
+- **Canon** (`canon`) → [clients/canon/INDEX.md](clients/canon/INDEX.md)
 - **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)
+- **Endeavor Health** (`endeavor-health`) → [clients/endeavor-health/INDEX.md](clients/endeavor-health/INDEX.md)
 - **Fordham University** (`fordham`) → [clients/fordham/INDEX.md](clients/fordham/INDEX.md)
 - **GroWrk** (`growrk`) → [clients/growrk/INDEX.md](clients/growrk/INDEX.md)
 - **Northwell Health** (`northwell`) → [clients/northwell/INDEX.md](clients/northwell/INDEX.md)
@@ -60,6 +62,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **Quad Graphics** (`quad`) → [clients/quad/INDEX.md](clients/quad/INDEX.md)
 - **Rate** (`rate`) → [clients/rate/INDEX.md](clients/rate/INDEX.md)
 - **Richmond University Medical Center** (`rumcsi`) → [clients/rumcsi/INDEX.md](clients/rumcsi/INDEX.md)
+- **S&P Global** (`spglobal`) → [clients/spglobal/INDEX.md](clients/spglobal/INDEX.md)
 - **Staples** (`staples`) → [clients/staples/INDEX.md](clients/staples/INDEX.md)
 - **Tow Foundation** (`tow-foundation`) → [clients/tow-foundation/INDEX.md](clients/tow-foundation/INDEX.md)
 - **TOGA Technology** (`true`) → [clients/true/INDEX.md](clients/true/INDEX.md)

package/knowledge/clients/aig/profile.md

@@ -6,13 +6,14 @@ apps:
   - api2
   - dbchanges2
   - library
+  - worker
   - worker2
 project: API
 client: aig
 type: profile
 status: active
-updated: 2026-08-17
-owners: ["mhammontree"]
+updated: 2026-08-29
+owners: ["mhammontree", "jcardinal"]
 files: []
 related:
   - clients/aig/features/entitlement-intake.md

package/knowledge/clients/canon/INDEX.md

@@ -0,0 +1,5 @@
+# Client: Canon `canon`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Canon](profile.md) | 2.0 | Canon is a **TOGa-Supply NetSuite integration client** on the shared 1.0 NetSuite → TOGa Supply per-client sync (`worker` + `library`). |  |

package/knowledge/clients/canon/profile.md

@@ -0,0 +1,34 @@
+---
+title: "Canon"
+framework: "2.0"
+apps:
+  - library
+  - worker
+project: Worker
+client: canon
+type: profile
+status: active
+updated: 2026-08-29
+owners: ["jcardinal"]
+files: []
+related:
+  - ../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
+---
+
+## Summary
+
+Canon is a **TOGa-Supply NetSuite integration client** on the shared 1.0 NetSuite → TOGa Supply
+per-client sync (`worker` + `library`). Its thin wrapper
+`worker/crons/toga2/netsuite/sync_togasupply_canon.php` is the **canonical example** referenced by
+the shared-engine doc — copy it when onboarding a new client. NetSuite transactions (sales orders,
+POs, invoices, item receipts, item fulfillments, inventory adjustments) sync into Canon's 2.0
+`Client_Canon` tenant through the TOGa2 API.
+
+This profile was seeded during the 2026-08-29 root-cause work that fixed Canon's stuck
+`ITEM_RECEIPTS` section — the item-receipt path was migrated SOAP → REST (`fetchItemReceiptById`);
+full mechanics and the diagnosis playbook live in
+[NetSuite → TOGa Supply per-client sync](../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
+
+## Integration touchpoints
+
+- **`worker` / `library` (1.0)** — the shared togasupply sync engine + `App_Api_Toga2` bridge.

package/knowledge/clients/endeavor-health/INDEX.md

@@ -0,0 +1,5 @@
+# Client: Endeavor Health `endeavor-health`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Endeavor Health](profile.md) | 2.0 | Endeavor Health is a **TOGa-Supply NetSuite integration client** on the shared 1.0 NetSuite → TOGa Supply per-client sync (`worker` + `library`). |  |

package/knowledge/clients/endeavor-health/profile.md

@@ -0,0 +1,32 @@
+---
+title: "Endeavor Health"
+framework: "2.0"
+apps:
+  - library
+  - worker
+project: Worker
+client: endeavor-health
+type: profile
+status: active
+updated: 2026-08-29
+owners: ["jcardinal"]
+files: []
+related:
+  - ../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
+---
+
+## Summary
+
+Endeavor Health is a **TOGa-Supply NetSuite integration client** on the shared 1.0 NetSuite → TOGa
+Supply per-client sync (`worker` + `library`). NetSuite transactions sync into Endeavor's 2.0
+`Client_<Id>` tenant through the TOGa2 API via a thin
+`worker/crons/toga2/netsuite/sync_togasupply_*.php` wrapper.
+
+This profile was seeded during the 2026-08-29 root-cause work that fixed Endeavor's stuck
+`ITEM_RECEIPTS` section — the item-receipt path was migrated SOAP → REST (`fetchItemReceiptById`);
+full mechanics and the diagnosis playbook live in
+[NetSuite → TOGa Supply per-client sync](../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
+
+## Integration touchpoints
+
+- **`worker` / `library` (1.0)** — the shared togasupply sync engine + `App_Api_Toga2` bridge.

package/knowledge/clients/nychh/INDEX.md

@@ -2,7 +2,7 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
-| [NYCHH inventory-adjustment → item-fulfillment linking (custbody_stock_adjustment bridges)](features/netsuite-inventory-adjustment-fulfillment-link.md) | 1.0 | For NYCHH stock adjustments, the NetSuite **inventory adjustment** carries a link to the **Item Fulfillment** it corrects, on the multi-select body custom field | library/app/api/toga2.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_hh.php, worker/crons/toga2/netsuite/diagnose_hh_import_inventory_adjustment.php, _underscore/Model/Client/ItemFulfillments/InventoryAdjustment.php, _underscore/Model/Client/ItemFulfillmentItems/InventoryAdjustmentItem.php, dbchanges2/Core/2026-08-27b - ItemFulfillmentsInventoryAdjustmentsBridge.sql, dbchanges2/Core/2026-08-28b - ItemFulfillmentItemsInventoryAdjustmentItemsBridge.sql, dbchanges2/Client/2026-08-27a - ItemFulfillmentsInventoryAdjustmentsBridgeTable.sql, dbchanges2/Client/2026-08-28c - ItemFulfillmentItemsInventoryAdjustmentItemsBridgeTable.sql |
+| [NYCHH inventory-adjustment → item-fulfillment linking (direct FK columns, REST)](features/netsuite-inventory-adjustment-fulfillment-link.md) | 1.0 | For NYCHH stock adjustments, the NetSuite **inventory adjustment** carries a link to the **Item Fulfillment** it corrects, on the multi-select body custom field | library/app/api/toga2.php, library/app/api/netsuite/rest.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_hh.php, worker/crons/toga2/netsuite/diagnose_hh_import_inventory_adjustment.php |
 | [NYCHH NetSuite → TransferOrders import (stocking-flag routing, PO bridges, origin location)](features/netsuite-transfer-order-import.md) | 1.0 | NYCHH's NetSuite **transfer orders are represented as NetSuite sales orders** (same as the GroWrk pattern), so the shared NetSuite → TOGa Supply importer (`App_ | library/app/api/toga2.php, library/app/api/netsuite/rest.php, library/app/netsuite.php, worker/crons/toga2/netsuite/sync_togasupply_hh.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/diagnose_hh_stuck_transfer_order.php, dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql, dbchanges2/Client/2026-08-28a - TransferOrderItemsTimestampColumns.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestampColumnsReposition.sql |
 | [NYCHH PO links are UPSTREAM — the downstream SO→PO route returns empty](features/po-number-upstream-direction.md) | 2.0 | NYCHH's sales orders are created **from the customer's purchase order**, so their SO↔PO links live in the **upstream** table `PurchaseOrders_SalesOrders` (route | _underscore/Model/Client/SalesOrder.php, _underscore/Trait/Netsuite/SalesOrder.php, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts, dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql, dbchanges2/Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql |
 | [NYCHH transfer-order 2.0 model — inventory quantities + V2 field enablement](features/transfer-order-inventory-quantities.md) | 2.0 | The 2.0 (`_underscore`) side of NYCHH transfer-order support: a **two-branch inventory quantity model** on the NYCHH `Item` override, plus the **client-override | _underscore/Model/Nychh/Item.php, _underscore/Model/Nychh/TransferOrder.php, _underscore/Model/Nychh/TransferOrderStage.php, _underscore/Model/Client/TransferOrder.php, _underscore/Model/Client/TransferOrderItem.php, dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql, dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql |

package/knowledge/clients/nychh/features/netsuite-inventory-adjustment-fulfillment-link.md

@@ -1,29 +1,28 @@
 ---
-title: "NYCHH inventory-adjustment → item-fulfillment linking (custbody_stock_adjustment bridges)"
+title: "NYCHH inventory-adjustment → item-fulfillment linking (direct FK columns, REST)"
 framework: "1.0"
 repo: library
 project: Library
 client: nychh
 type: client-feature
 status: active
-updated: 2026-08-28
+updated: 2026-08-29
 owners: [jcardinal]
 files:
   - library/app/api/toga2.php
+  - library/app/api/netsuite/rest.php
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
   - worker/crons/toga2/netsuite/sync_togasupply_hh.php
   - worker/crons/toga2/netsuite/diagnose_hh_import_inventory_adjustment.php
-  - _underscore/Model/Client/ItemFulfillments/InventoryAdjustment.php
-  - _underscore/Model/Client/ItemFulfillmentItems/InventoryAdjustmentItem.php
-  - dbchanges2/Core/2026-08-27b - ItemFulfillmentsInventoryAdjustmentsBridge.sql
-  - dbchanges2/Core/2026-08-28b - ItemFulfillmentItemsInventoryAdjustmentItemsBridge.sql
-  - dbchanges2/Client/2026-08-27a - ItemFulfillmentsInventoryAdjustmentsBridgeTable.sql
-  - dbchanges2/Client/2026-08-28c - ItemFulfillmentItemsInventoryAdjustmentItemsBridgeTable.sql
 related:
   - ./netsuite-transfer-order-import.md
   - ./transfer-order-inventory-quantities.md
   - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
   - ../../../1.0/apps/library/features/toga2-api-client-and-bridge.md
+  - ../../../1.0/apps/library/features/netsuite-suiteql-api-reference.md
+  - ../../../1.0/apps/library/features/netsuite-suiteql-rest-shim.md
+  - ../../../2.0/apps/api2/features/v2-rest-query-contract.md
+  - ../../../2.0/apps/api2/features/request-logging.md
   - ../../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md
   - ../profile.md
 ---
@@ -32,86 +31,134 @@ related:
 
 For NYCHH stock adjustments, the NetSuite **inventory adjustment** carries a link to the **Item
 Fulfillment** it corrects, on the multi-select body custom field **`custbody_stock_adjustment`**
-(internalId **9735**). This feature imports that link into TOGa Supply as two new bridge tables
-(header + line), so H&H gets **adjustment → item fulfillment → sales order → purchase order**
-traceability for their PO-specific fulfillment. Per the **2026-08-27 TOGa Supply meeting**; the
-NetSuite custom field was implemented **<1 year ago**, so older adjustments carry **no** link.
-
-Like [NYCHH transfer-order import](./netsuite-transfer-order-import.md), the **tables and models are
-all-client infrastructure** (`dbchanges2/Client/` + shared `_Model_Client_*` bridge models) but the
-**attach is gated NYCHH-only** by `IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING`.
-
-## The two bridges (both mirror the transfer-order bridge pattern)
-
-| Level | Bridge table | `Core.Records` id | `RecordFields` | Model |
-|---|---|---|---|---|
-| Header | `ItemFulfillments_InventoryAdjustments` | 353 | 2515–2518 | `_Model_Client_ItemFulfillments_InventoryAdjustment` |
-| Item | `ItemFulfillmentItems_InventoryAdjustmentItems` | 354 | 2519–2522 | `_Model_Client_ItemFulfillmentItems_InventoryAdjustmentItem` |
-
-Each shipped as: an all-client `Client/` bridge table, Core registration (`Records` + `RecordFields`),
-a Super-User ACL grant, and a per-client ACL **copied from the parent record**. The parent record
-uuids are already `isIdentifier = 1`, so — unlike the transfer-order bridges — **no `EV-12`
-uuid-identifier fix was needed** (contrast the 312/313 anomaly on
-[the ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md)).
-
-> **Bridge FK writes via a nested `{uuid}` need only record-level ACL, not field-level.** Verified
-> against the existing transfer-order bridges — the nested-write ACL check is at the record level for a
-> bridge link, so no `AclCustomFieldPermissions` grant is required on the FK columns.
+(internalId **9735**). This feature imports that link into TOGa Supply so H&H gets **adjustment →
+item fulfillment → sales order → purchase order** traceability for their PO-specific fulfillment.
+Per the **2026-08-27 TOGa Supply meeting**; the NetSuite custom field was implemented **<1 year
+ago**, so older adjustments carry **no** link.
+
+**Current design (2026-08-29): direct FK columns, over REST.** The link is now stored as **two
+direct FK columns** — `InventoryAdjustments.itemFulfillmentId` and
+`InventoryAdjustmentItems.itemFulfillmentItemId` — **replacing** the two bridge tables the
+prior-session build used (`ItemFulfillments_InventoryAdjustments` /
+`ItemFulfillmentItems_InventoryAdjustmentItems`). And the whole inventory-adjustment sync — plus the
+on-demand fulfillment/sales-order import it triggers — was **migrated from SOAP to REST** for speed
+(the SOAP path was ~2 NetSuite round-trips per serial, ~1h for a large serialized adjustment).
+
+Like [NYCHH transfer-order import](./netsuite-transfer-order-import.md), the FK columns and models
+are **all-client infrastructure** but the **attach is gated NYCHH-only** by
+`IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING`.
+
+## The two FK links (replaced the header/line bridge tables)
+
+| Level | FK column | `Core.Records` | `Core.RecordFields` |
+|---|---|---|---|
+| Header | `InventoryAdjustments.itemFulfillmentId` | 154 (InventoryAdjustments) | reuses 2517 |
+| Item | `InventoryAdjustmentItems.itemFulfillmentItemId` | 155 (InventoryAdjustmentItems) | reuses 2521 |
+
+The FK columns **reuse the `RecordFields` already registered/granted from the earlier bridge work**
+(2517 on record 154, 2521 on record 155), so this change needed **no new Core registration or ACL
+grant** — the bridge tables (records 353/354) and their per-client copies are superseded. Writing a
+link is now a plain PUT of the FK uuid onto the parent record, not a bridge-row insert.
 
 ## Attach code — `App_Api_Toga2::attachInventoryAdjustmentToItemFulfillment`
 
 Lives in `library/app/api/toga2.php`, called from `syncInventoryAdjustmentFromNetsuite` **after the
-header upsert**, gated on `IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING`, and wrapped in
-`try/catch` — it is **best-effort and must never freeze the section** (a failed link is logged, the
-adjustment import still completes). It:
+header upsert**, gated on `IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING`. It:
 
 1. reads `custbody_stock_adjustment` off the adjustment (the related Item Fulfillment),
 2. resolves that fulfillment by `ItemFulfillments.c_netsuiteInternalItemFulfillmentId`,
-3. idempotently creates the **header** link row, then
-4. links **line items** by matching `itemId` — every same-product adjustment-item ↔ fulfillment-item
-   pair is linked; the bridge's `UNIQUE(fk, fk)` dedupes re-runs.
-
-## On-demand dependency import (fulfillment not yet in TOGA)
-
-When the linked fulfillment has **not** been imported into TOGA yet, the attach no longer skips and
-waits for the fulfillment backfill — it **imports the fulfillment on demand** via
-`syncItemFulfillmentFromNetsuite` (which itself cascades to the originating sales order when missing),
-then **re-resolves and links**.
-
-This required threading the **full item-fulfillment lookup set** — customer, country, state, location,
-manufacturer, item, all-catalog-items, vendor-item, shipping-carrier, shipping-method, warehouse —
-through `syncInventoryAdjustmentFromNetsuite` (signature **expanded 5 → 13 args**) and into
-`attachInventoryAdjustmentToItemFulfillment`, plus updating the `common_sync_togasupply.php`
-`INVENTORY_ADJUSTMENTS` call to pass them (the same set already passed to the item-fulfillment
-section). **Design rule (developer instruction): all lookups are passed function-to-function**, like
-the other sync functions — not rebuilt or fetched inside the callee.
-
-## Two fixes in `syncInventoryAdjustmentFromNetsuite` (shared engine, surfaced by the harness)
-
-Both are in the shared library method, so they affect **any** client running inventory adjustments —
-see also the [per-client sync](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md):
+3. writes the **header** FK (`InventoryAdjustments.itemFulfillmentId`), then
+4. writes the **line** FK (`InventoryAdjustmentItems.itemFulfillmentItemId`) for each
+   same-product adjustment-item ↔ fulfillment-item pair, matched by product `item` uuid.
+
+### ⚠ Reading the product uuid needs `depth=3` (the max-depth omission trap)
+
+Step 4's product match reads `salesOrderItem->item->uuid` from `GET /item-fulfillment-items`. The
+V2 read engine **omits a non-null FK object that sits at the max requested `depth`** — and a null
+sibling FK still renders, so the omission is easy to miss. At `depth=2` the grandchild `item`
+(level 3: `itemFulfillmentItem → salesOrderItem → item`) was dropped → the product-match map was
+empty → **no `itemFulfillmentItemId` was written**. Fix: request **`depth=3`** *plus* explicit
+nested fields `salesOrderItem.item.uuid` / `transferOrderItem.item.uuid`. Framework detail:
+[V2 REST query contract — max-depth FK omission](../../../2.0/apps/api2/features/v2-rest-query-contract.md).
+
+### ⚠ The FK write's PUT echo may not reflect what persisted
+
+A `PUT /v2/inventory-adjustments/{uuid}` with `{"itemFulfillment":{"uuid":…}}` returned **200,
+empty `messages[]`, and an echo that did NOT contain `itemFulfillment`** — yet the FK column
+**persisted correctly**. Do not read an empty echo as a failed write; verify against the DB or the
+`Logs_<Client>.Api` `responsePayload`. This was diagnosed entirely from `Logs_Nychh.Api` (routes
+stored with the `/v2` prefix — filter `route LIKE '/v2/...'`), with **no NetSuite access needed**.
+See [V2 request logging](../../../2.0/apps/api2/features/request-logging.md).
+
+### Loud failure (best-effort try/catch removed)
+
+The attach and the surrounding NetSuite→DB sync path **no longer swallow errors**: the
+error-log-and-swallow `try/catch` blocks were removed so a data-corruption failure surfaces loudly
+(StarTech/Sentry catches left alone). This is the same loud-failure policy as the 2026-08-27 removal
+of the per-order `try/catch` skips across all six sync sections — see
+[NetSuite → TOGa Supply per-client sync](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
+**Do not "soften" this back into a swallow** — a bridge/link miss must be visible, not silently
+dropped.
+
+## On-demand dependency import (fulfillment not yet in TOGA) — now REST
+
+When the linked fulfillment has **not** been imported into TOGA yet, the attach **imports the
+fulfillment on demand** via `syncItemFulfillmentFromNetsuite` (which itself cascades to the
+originating sales order when missing), then **re-resolves and links**. This on-demand import was
+**converted from SOAP to REST** this session.
+
+Threading the on-demand import required the **full item-fulfillment lookup set** — customer,
+country, state, location, manufacturer, item, all-catalog-items, vendor-item, shipping-carrier,
+shipping-method, warehouse — to be passed through `syncInventoryAdjustmentFromNetsuite` (signature
+**expanded 5 → 13 args**) and into `attachInventoryAdjustmentToItemFulfillment`, plus updating the
+`common_sync_togasupply.php` `INVENTORY_ADJUSTMENTS` call to pass them. **Design rule (developer
+instruction): all lookups are passed function-to-function**, like the other sync functions — not
+rebuilt or fetched inside the callee.
+
+## The REST-shim fixes this migration required (`library/app/api/netsuite/rest.php`)
+
+Both are framework-level NetSuite facts — full detail on
+[NetSuite SuiteQL/REST API Reference](../../../1.0/apps/library/features/netsuite-suiteql-api-reference.md):
+
+- **Item-fulfillment REST shim returned zero line items.** `fetchItemFulfillmentById` fetched
+  fulfillment lines from the REST **record sublist** `GET /record/v1/itemFulfillment/{id}/item?limit=1000&offset=N`.
+  **REST record sublist endpoints reject `limit`/`offset`** (HTTP 400 `INVALID_PARAMETER`), so the
+  shim silently got 0 lines and every fulfillment imported **header-only** — starving all downstream
+  ItemFulfillmentItems and the line-level link. **Fix:** fetch lines via SuiteQL `transactionline`
+  (the pattern every other shim in the file already uses).
+- **Fulfillment SuiteQL returned ~3 rows per fulfilled item.** An Item Fulfillment (`ItemShip`) has
+  three `transactionline` rows per fulfilled item: the order-linked line, a positive "wash" line, and
+  an `isinventoryaffecting='T'` line — only the order-linked line maps to a source-order line.
+  **Fix:** keep only lines with a `previoustransactionlinelink` of type `SalesOrd`/`TrnfrOrd` (via
+  `EXISTS`), and derive `orderLine` from that link's `previousline` (correlated subquery).
+  **`mainline='F'` is the WRONG filter** — NetSuite sometimes marks the first real fulfilled line
+  `mainline='T'`.
+
+## Two shared-engine fixes in `syncInventoryAdjustmentFromNetsuite` (surfaced here, affect any client)
+
+Both are in the shared library method — see also the
+[per-client sync](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md):
 
 - **(a) Prune-order FK violation.** The stale-item prune deleted an `InventoryAdjustmentItem` while
   its child `InventoryAdjustmentItemUnits` still referenced it (FK **RESTRICT**, no cascade) → MySQL
   **1451** → `EV-11`. **Fix:** delete the child units (`/inventory-adjustment-item-units/{uuid}`)
-  **before** the item. (Same "delete bridge/child rows first" rule as the tracking-number bridges.)
-- **(b) Item-lookup indexing mismatch → duplicate items every run.** The item lookup was consumed as a
-  **two-level** `[$uuidManufacturer][$partNumber]`, but the cron passes it **one-level** `[$partNumber]`
-  (populated in `common_sync_togasupply.php` ~L313). The two-level
-  `$lookupItemByClientUuidAndManufacturerUuidAndPartNumberUpper` is declared but **never populated
-  (dead)**. The mismatch meant existing items were never found, so items were **re-created every run**
-  (duplicates / `EV-10`). **Fix:** index one-level `[$partNumber]`.
+  **before** the item. (Same "delete child rows first" rule as the tracking-number bridges.)
+- **(b) Item-lookup indexing mismatch → duplicate items every run.** The item lookup was consumed
+  **two-level** `[$uuidManufacturer][$partNumber]`, but the cron passes it **one-level**
+  `[$partNumber]` (populated in `common_sync_togasupply.php` ~L313); the two-level lookup is declared
+  but **never populated (dead)**. Existing items were never found, so items were **re-created every
+  run** (duplicates / `EV-10`). **Fix:** index one-level `[$partNumber]`.
 
 ## Diagnostic harness — `diagnose_hh_import_inventory_adjustment.php`
 
 A **manual operator tool** in `worker/crons/toga2/netsuite/` (NOT in `cron.worker.sync.json`; does
 **not** call `cronInitialization`, so no process lock / no cursor writes; installs a strict
 `set_error_handler` that rethrows warnings as `ErrorException` for exact crash lines). It imports
-**one** inventory adjustment (default NS internal id **6516616**) by calling the real
-`syncInventoryAdjustmentFromNetsuite`, seeds the warehouse/item/manufacturer lookups (the item loop
-**filters** items to known warehouses and **creates** items on a lookup-miss, so empty lookups drop or
-duplicate items), and has a **read-only** diagnostic tail that dumps the NS item list +
-`custbody_stock_adjustment` + whether the referenced fulfillment already exists in TOGA.
+**one** inventory adjustment by calling the real `syncInventoryAdjustmentFromNetsuite`, seeds the
+warehouse/item/manufacturer lookups (the item loop **filters** items to known warehouses and
+**creates** items on a lookup-miss, so empty lookups drop or duplicate items), and has a
+**read-only** diagnostic tail that dumps the NS item list + `custbody_stock_adjustment` + whether the
+referenced fulfillment already exists in TOGA.
 
 ```
 php crons/toga2/netsuite/diagnose_hh_import_inventory_adjustment.php <togaClient> <togaApi> <togaSecret> [adjustmentInternalId]
@@ -120,53 +167,53 @@ php crons/toga2/netsuite/diagnose_hh_import_inventory_adjustment.php <togaClient
 
 ## Go-live toggle
 
-`IS_ENABLED_INTEGRATION_INVENTORY_ADJUSTMENTS` is still **`false`** in `sync_togasupply_hh.php` —
-enabling it is the go-live switch for this feature on the scheduled cron.
-
-## Open / next-session — migrate the inventory-adjustment sync from SOAP to REST
-
-The inventory-adjustment sync is still **SOAP**: `App_NetSuite::getInventoryNumberFromSerialNumber` +
-`getInventoryNumber` per serial (`toga2.php` ~5371/5374), plus `getObject('inventoryAdjustment')`,
-`getItemDetails`, `detectItemType`, `getItemIsSerialized`, `getItemIsFulfillable`. For a **serialized**
-adjustment this is ~2 NetSuite SOAP round-trips **per serial** → ~1 hour for a large adjustment; the
-on-demand fulfillment import inherits the same cost. **Decision:** migrate the whole
-inventory-adjustment sync to REST via `App_Api_Netsuite_Rest` (`rest.php` already has
-`send`/`authenticate`/`suiteqlListAll`/`getCustomFieldValue`/`fetchItemById`/`listInventoryAdjustments`
-(minimal) — the gaps are a full inventory-adjustment fetch with inventory detail/serials, and an
-inventory-number/serial batch lookup). **This is the next session's task.**
+`IS_ENABLED_INTEGRATION_INVENTORY_ADJUSTMENTS` in `sync_togasupply_hh.php` is the go-live switch for
+this feature on the scheduled cron.
 
-## Known state — test adjustment 6516616
+## Validation (end-to-end, prod)
 
-NYCHH adjustment **6516616** (tranId **2136**) has **4 NON-serialized** items (adjustQtyBy
-1800/1800/700/40) and `custbody_stock_adjustment` → Item Fulfillment **#289938** (NS internal
-6507274). That fulfillment is **not yet imported** in TOGA, so the bridges stay empty until the
-on-demand import lands it. Import + item-sync of the adjustment itself works (4
-`InventoryAdjustmentItems`).
+- **Non-serialized:** linked adjustment **6994071** → fulfillment **6827251** — header FK + line FK
+  both populate.
+- **Serialized:** linked adjustment **6871592** → fulfillment **6868763** (2 serials) — header FK,
+  line FK, **and 2 serial units on BOTH** the adjustment item and the fulfillment item all populate
+  correctly.
 
 ## Gotchas / known issues
 
 - **Older adjustments have no link.** `custbody_stock_adjustment` was added in NetSuite <1 year ago;
-  adjustments predating it will never populate a bridge — not a bug.
-- **The attach is best-effort by design.** It is gated NYCHH-only and wrapped in `try/catch`; a link
-  failure logs and lets the adjustment import complete. Do not "harden" it into a throw — a bridge miss
-  must not freeze `INVENTORY_ADJUSTMENTS`.
+  adjustments predating it will never populate an FK — not a bug.
+- **Reading the product uuid at `depth=2` silently returns nothing** — the level-3 `item` object is
+  omitted at max depth. Use `depth=3` + explicit nested `fields` (see above).
+- **A V2 PUT echo that omits `itemFulfillment` does NOT mean the write failed** — verify against the
+  DB / `Logs_<Client>.Api`, not the echoed body.
 - **Empty lookups drop or duplicate items.** The item loop filters to known warehouses and creates
   items on lookup-miss, so any manual/diagnostic invocation must seed the warehouse/item/manufacturer
   lookups (the harness does).
 
 ## Change history
 
-- 2026-08-28 — Built NYCHH inventory-adjustment → item-fulfillment linking off NetSuite
-  `custbody_stock_adjustment` (internalId 9735): two all-client bridges
-  (`ItemFulfillments_InventoryAdjustments` record 353 / `ItemFulfillmentItems_InventoryAdjustmentItems`
-  record 354, Core-registered + Super-User/per-client ACL), a gated best-effort
-  `App_Api_Toga2::attachInventoryAdjustmentToItemFulfillment` (resolves the fulfillment by
-  `c_netsuiteInternalItemFulfillmentId`, idempotent header + itemId-matched line links), and **on-demand
-  import** of a not-yet-imported fulfillment via `syncItemFulfillmentFromNetsuite` (cascades to the SO)
-  — which expanded `syncInventoryAdjustmentFromNetsuite` 5→13 args to thread the full IF lookup set.
-  Fixed two shared-engine bugs: the stale-item prune deleted an item before its child units (FK
-  RESTRICT → 1451/EV-11 — now deletes units first), and the item lookup was consumed two-level while the
-  cron populates it one-level `[$partNumber]` (re-created items every run → duplicates/EV-10 — now
-  one-level). Added the `diagnose_hh_import_inventory_adjustment.php` operator harness. Go-live toggle
-  `IS_ENABLED_INTEGRATION_INVENTORY_ADJUSTMENTS` still false. **Open (next session):** migrate the
-  inventory-adjustment sync from SOAP (~2 round-trips/serial, ~1h for a large adjustment) to REST. (jcardinal)
+- 2026-08-29 — **Migrated the feature to direct FK columns over REST, and made it fail loud.**
+  Replaced the two bridge tables with direct FK columns
+  (`InventoryAdjustments.itemFulfillmentId` reusing `RecordField` 2517/record 154;
+  `InventoryAdjustmentItems.itemFulfillmentItemId` reusing 2521/record 155 — no new Core
+  registration/ACL). Migrated `syncInventoryAdjustmentFromNetsuite` and its on-demand
+  fulfillment/sales-order import **SOAP → REST** (was ~2 round-trips/serial → ~1h for a large
+  serialized adjustment), and removed the error-log-and-swallow `try/catch` in the NetSuite→DB sync
+  path (StarTech/Sentry catches left alone). Fixed three read-path traps hit along the way: the REST
+  **record-sublist `limit`/`offset` 400** (`fetchItemFulfillmentById` returned 0 lines → header-only
+  import; now uses SuiteQL `transactionline`), the **ItemShip 3-rows-per-item** filter (keep the
+  `SalesOrd`/`TrnfrOrd` line-linked line, `mainline='F'` is wrong), and the **V2 max-depth FK
+  omission** (`depth=2` dropped `salesOrderItem.item` → now `depth=3` + explicit nested fields).
+  Discovered a **V2 PUT echo can omit a field that persisted** (verified via `Logs_Nychh.Api`, no
+  NetSuite access). Validated end-to-end in prod: non-serialized 6994071→6827251 and serialized
+  6871592→6868763 (header FK, line FK, and 2 serial units on both sides). (jcardinal)
+- 2026-08-28 — Built the initial NYCHH inventory-adjustment → item-fulfillment linking off NetSuite
+  `custbody_stock_adjustment` (internalId 9735) as **two all-client bridge tables** (header record
+  353 / item record 354, Core-registered + Super-User/per-client ACL) with a gated best-effort
+  `App_Api_Toga2::attachInventoryAdjustmentToItemFulfillment` and **on-demand import** of a
+  not-yet-imported fulfillment via `syncItemFulfillmentFromNetsuite` (cascades to the SO) — which
+  expanded `syncInventoryAdjustmentFromNetsuite` 5→13 args to thread the full IF lookup set. Fixed the
+  two shared-engine bugs (prune child units before the item — FK RESTRICT/1451/EV-11; index the item
+  lookup one-level `[$partNumber]` — was two-level dead → duplicates/EV-10). Added the
+  `diagnose_hh_import_inventory_adjustment.php` operator harness. *(This bridge-table design was
+  superseded by the 2026-08-29 direct-FK / REST migration above.)* (jcardinal)

package/knowledge/clients/spglobal/INDEX.md

@@ -0,0 +1,5 @@
+# Client: S&P Global `spglobal`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [S&P Global](profile.md) | 2.0 | S&P Global is a **TOGa-Supply NetSuite integration client** on the shared 1.0 NetSuite → TOGa Supply per-client sync (`worker` + `library`). |  |

package/knowledge/clients/spglobal/profile.md

@@ -0,0 +1,32 @@
+---
+title: "S&P Global"
+framework: "2.0"
+apps:
+  - library
+  - worker
+project: Worker
+client: spglobal
+type: profile
+status: active
+updated: 2026-08-29
+owners: ["jcardinal"]
+files: []
+related:
+  - ../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
+---
+
+## Summary
+
+S&P Global is a **TOGa-Supply NetSuite integration client** on the shared 1.0 NetSuite → TOGa Supply
+per-client sync (`worker` + `library`). NetSuite transactions sync into its 2.0 `Client_<Id>` tenant
+through the TOGa2 API via a thin `worker/crons/toga2/netsuite/sync_togasupply_*.php` wrapper.
+
+This profile was seeded during the 2026-08-29 root-cause work on the stuck togasupply integrations:
+S&P Global was one of the clients exposed to the item-fulfillment "Undefined index" on an empty
+`orderLine` (`syncItemFulfillmentFromNetsuite`), fixed in shared code. Full mechanics and the
+diagnosis playbook live in
+[NetSuite → TOGa Supply per-client sync](../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
+
+## Integration touchpoints
+
+- **`worker` / `library` (1.0)** — the shared togasupply sync engine + `App_Api_Toga2` bridge.

package/package.json

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