toga-ai 1.0.693 → 1.0.694

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-18
+updated: 2026-08-28
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -504,8 +504,33 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
   `NETSUITE_LAST_SYNC_DATETIME_*` frozen watermark), then read `Logs.Issue` — not `Logs_<Client>.Api`
   — for the throwing order.
 
+- **⚠ Inventory-adjustment sync: two shared-engine bugs + it is still SOAP (2026-08-28).** Both fixed
+  in `syncInventoryAdjustmentFromNetsuite` (`library/app/api/toga2.php`) and reachable by any client
+  running inventory adjustments: (a) the stale-item prune deleted an `InventoryAdjustmentItem` before
+  its child `InventoryAdjustmentItemUnits` (FK **RESTRICT** → MySQL 1451 → `EV-11`) — now deletes the
+  child units first; (b) the item lookup was consumed **two-level**
+  `[$uuidManufacturer][$partNumber]` while the cron populates it **one-level** `[$partNumber]`
+  (`common_sync_togasupply.php` ~L313; the two-level lookup is declared but never populated — dead), so
+  existing items were never matched and **re-created every run** (duplicates / `EV-10`) — now indexed
+  one-level. Also: the section is **still SOAP** (`App_NetSuite::getInventoryNumber*` ~2 round-trips
+  **per serial** → ~1h for a large serialized adjustment); a REST migration via `App_Api_Netsuite_Rest`
+  is the planned next step. Surfaced building NYCHH's adjustment→fulfillment linking; full detail on
+  [NYCHH inventory-adjustment → item-fulfillment linking](../../../clients/nychh/features/netsuite-inventory-adjustment-fulfillment-link.md).
+  Note `syncInventoryAdjustmentFromNetsuite`'s signature was expanded **5 → 13 args** to thread the full
+  item-fulfillment lookup set through for the on-demand fulfillment import (lookups are passed
+  function-to-function, like the other sync functions).
+
 ## Change history
 
+- 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
+  populates, was two-level dead → items re-created every run / duplicates / EV-10), the 5→13-arg
+  signature expansion that threads the full IF lookup set for on-demand fulfillment import, and that the
+  section is **still SOAP** (~2 round-trips/serial → ~1h large adjustment; REST migration planned).
+  Surfaced building NYCHH's adjustment→fulfillment linking — see
+  [NYCHH inventory-adjustment → item-fulfillment linking](../../../clients/nychh/features/netsuite-inventory-adjustment-fulfillment-link.md).
+  (jcardinal)
 - 2026-08-27 — **Removed a silent data-loss bug: all per-order `catch (Throwable)` skips and all
   section-level `try/finally` were deleted, so every section now fails LOUD.** A 2026-08-20 change had
   wrapped each order dispatch in `catch (Throwable) { error_log }` and each section in

package/knowledge/2.0/apps/_underscore/INDEX.md

@@ -4,7 +4,7 @@
 |-----|---------|-------|
 | [Proposed — git-sourced base+overlay JSON authoring for the Surface layer](architecture/surface-authoring-proposal.md) | A **proposal / handoff recommendation** (not implemented) that the Surface layer's *authoring* model move off hand-authored SQL against the `SurfaceOverrides` E | _underscore/Model/Core/Surface.php, _underscore/Model/Client/SurfaceOverride.php |
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
-| [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, _underscore/Model/Core/Surface.php, _underscore/Model/Client/TrackingNumber.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission.sql, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql, dbchanges2/Client_Quad/2026-08-24 - Quad Multi Currency Item Pricing.sql |
+| [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql, _underscore/Model/Core/Page.php, _underscore/Model/Core/Surface.php, _underscore/Model/Client/TrackingNumber.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql, dbchanges2/Client/2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission.sql, dbchanges2/Client/2026-07-22c - TrackingNumberMeasureIdsFieldPermission.sql, dbchanges2/Client_Quad/2026-08-24 - Quad Multi Currency Item Pricing.sql |
 | [Address Uniqueness Normalization (unit identifier + 5-digit ZIP comparison)](features/address-uniqueness-normalization.md) | When a business rule says *"only one X per physical address"*, comparing address rows field-for-field does **not** work: the same dwelling is spelled many diffe | _underscore/Model/Rate/Entitlement.php |
 | [Address Validation (carrier waterfall + validateAddress scripted endpoint)](features/address-validation.md) | `_Model_Client_Address::validateAddress` verifies a US address against a **carrier waterfall (USPS → FedEx → UPS)** and returns a single canonical, carrier-norm | _underscore/Model/Client/Address.php, _underscore/Component/Library/Carriers/Usps/Usps.php |
 | [_ApiRequest — JSON encode/decode & api-logging behavior](features/apirequest-json-content-type.md) | `_ApiRequest` is the 2.0 outbound HTTP client. | _underscore/ApiRequest.php |

package/knowledge/2.0/apps/_underscore/features/acl-permission-chain.md

@@ -10,6 +10,7 @@ updated: 2026-08-28
 owners: ["jcardinal", "mhammontree", "tcox", "bala"]
 files:
   - api2/Component/Api/V2/V2.php
+  - dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql
   - _underscore/Model/Core/Page.php
   - _underscore/Model/Core/Surface.php
   - _underscore/Model/Client/TrackingNumber.php
@@ -242,6 +243,18 @@ column + `CustomRecordFields` row + `AclCustomFieldPermissions` grant + model de
 2026-08-27 on NYCHH `c_netsuiteInternalTransferOrderStatus` (recordId 351): the field existed and was
 granted, but the nested transfer-order-stage lookup 400'd until `isIdentifier` was set to 1.
 
+> **The same rule bites the base `uuid` field, not just `c_` fields.** When a nested write links its
+> parent **by `uuid`** (the normal case for a `{uuid}` nested reference), that record's
+> `RecordFields.uuid.isIdentifier` must be `1` or `searchableIdentifierFields` excludes `uuid` and the
+> write 400s `EV-12`. Every record normally ships with `uuid.isIdentifier = 1` (e.g. SalesOrders record
+> 14) — but **records 312 (`TransferOrders`) and 313 (`TransferOrderItems`) were the platform-wide
+> anomaly**: their `uuid.isIdentifier` was `0`, so a nested `transferOrder:{uuid}` write on the
+> transfer-order-items POST could not resolve its parent and froze the sync. Fixed platform-wide
+> (`dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql`, `isIdentifier = 1` on
+> records 312/313 `uuid`). When an `EV-12` mentions `searchableIdentifierFields:[id]` on a plain
+> `{uuid}` nested write, check `Core.RecordFields.uuid.isIdentifier` for that record before anything
+> else.
+
 **The `c_` declaration on a client-override model comes from its NetSuite trait.** The pattern for a
 NetSuite-synced record is `_Model_<Client>_X extends _Model_Client_X { use _Trait_Netsuite_X; }` — the
 trait is what declares the `c_` fields (so a client with only `extends`, no `use`, is missing them and
@@ -488,6 +501,11 @@ hardcoded `Core.RecordFields` id literals instead of a subselect.
   the space `Records.aclDatabase` selects — **`Core.Roles`** ids for a `CORE` record such as
   `surfaces` (`V2.php` ~L3090 / ~L6198), with `id.core.roles` derived from
   `Roles.coreRoleId` (~L1611-1627) and therefore usually just Base. (bala)
+- 2026-08-28 — Extended the `isIdentifier` rule to the **base `uuid` field**: a nested `{uuid}` write
+  resolves its parent only if that record's `RecordFields.uuid.isIdentifier = 1`, else `EV-12`. Records
+  **312 (`TransferOrders`) / 313 (`TransferOrderItems`)** were the platform-wide anomaly (uuid
+  `isIdentifier = 0`), which froze the transfer-order-items POST; fixed platform-wide by
+  `dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql`. (jcardinal)
 - 2026-08-27 — Recorded two facts from wiring NYCHH transfer-order custom fields: **there is NO
   ACL/metadata cache** (`buildLookups()` re-reads per request, so a new grant/metadata row applies on
   the next request — no cache-bust exists; a whole debugging pass was wasted assuming one did), and a

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

@@ -223,6 +223,31 @@ corresponding committed file — are in
 [surface-layer-schema](../apps/dbchanges2/features/surface-layer-schema.md) and
 [surface-resolver](../apps/_underscore/features/surface-resolver.md).
 
+### Standard column ordering — `id`, `uuid`, `dtCreated`, `dtUpdated`, then the rest
+
+Every table uses a fixed leading column order: `id` (primary key), then `uuid`, then **`dtCreated`
+immediately after `uuid`**, then **`dtUpdated` immediately after `dtCreated`**, and the business
+columns after that. This is a hard, fundamental team convention — it keeps the audit columns in the
+same, predictable place on every table platform-wide.
+
+- **New tables (`CREATE TABLE`):** declare the columns in that order.
+- **Adding the timestamps to an existing table (`ALTER TABLE`):** position them explicitly with
+  `AFTER`, because a bare `ADD COLUMN` appends to the **end** of the table and violates this standard:
+
+  ```sql
+  ALTER TABLE MyTable
+      ADD COLUMN dtCreated DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP AFTER uuid,
+      ADD COLUMN dtUpdated DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP AFTER dtCreated;
+  ```
+
+  To reposition timestamps already appended at the end of an existing table, use
+  `MODIFY COLUMN dtCreated ... AFTER uuid` / `MODIFY COLUMN dtUpdated ... AFTER dtCreated`.
+
+`dtCreated` / `dtUpdated` are `DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP` (with `dtUpdated` also
+`ON UPDATE CURRENT_TIMESTAMP`), matching the model's `FIELD_DATETIME_CREATED` /
+`FIELD_DATETIME_UPDATED` field types. Bridge tables that carry no timestamps (only `id`, `uuid`, and
+the two FK columns) are exempt — the rule is about *where* the timestamps go when a table has them.
+
 ## Checking dependencies before touching shared code
 
 `dependsOn` in `knowledge/registry.json` means a repo extends or depends on another repo's classes. Before modifying a class in a dependency repo (e.g. `_underscore` core):
@@ -308,6 +333,11 @@ ACL-governed field treatment.
   did not write them back, so current state must be established with read-only queries against the
   target environment, and the cluster-isolation hook catches cross-database references but
   **cannot** catch state drift. (apeterson)
+- 2026-08-28 — Documented the **standard leading column order** (`id`, `uuid`, then `dtCreated`
+  immediately after `uuid`, then `dtUpdated` immediately after `dtCreated`, then business columns),
+  including using `AFTER` on `ALTER TABLE ADD COLUMN` so timestamps are positioned rather than
+  appended. Prompted by the platform-wide `TransferOrderItems` drift where the audit columns were
+  missing entirely. (jcardinal)
 - 2026-07-29 — Documented the `c_`-prefixed framework-dynamic column convention (schema-only,
   no model-class/RecordFields/ACL declaration), generalized from the transcript AI-model routing
   work. (ajean)

package/knowledge/INDEX.md

@@ -4,7 +4,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 20 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 21 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 31 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)

package/knowledge/clients/growrk/profile.md

@@ -5,6 +5,7 @@ apps:
   - _underscore
   - api2
   - worker2
+  - worker
   - toga2-supply
   - dbchanges2
   - library
@@ -12,8 +13,8 @@ project: _Underscore
 client: growrk
 type: profile
 status: active
-updated: 2026-08-10
-owners: ["rgirish", "mhammontree", "bala"]
+updated: 2026-08-28
+owners: ["rgirish", "mhammontree", "bala", "jcardinal"]
 files: []
 related:
   - clients/growrk/features/transfer-order-flow.md
@@ -56,6 +57,13 @@ module (`dbchanges2/Client_Growrk/_modules.txt`).
   2026-08-01, but it fails `POST /item-fulfillments` with **EV-12** and makes the Fulfill & Ship
   ship-to address arbitrary (`salesOrders[0]`). Needs its own ticket — see the
   [Fulfill & Ship gotchas](../../2.0/apps/toga2-supply/features/fulfill-and-ship.md).
+- **GroWrk runs the shared 1.0 NetSuite→TOGa Supply sync (`worker`/`library`), and its transfer
+  orders share the transfer-order code path.** The 2026-08-28 `SALES_ORDERS` freeze on
+  `syncTransferOrderFromNetsuite` (the api2-omits-a-null-FK `$transferOrderStage` warning →
+  fatal, plus the platform-wide `TransferOrderItems` missing-timestamp-columns 1054) hit GroWrk too,
+  not just NYCHH; both were fixed in shared code. See
+  [NYCHH NetSuite → TransferOrders import](../nychh/features/netsuite-transfer-order-import.md) (freeze
+  chain) — the fixes are shared, only the routing gate is NYCHH-specific.
 - **`ShippingMethods` ids 11/12 ("Overnight Standard"/"Overnight Priority") have NULL `code`** — FedEx
   product names on UPS rows, duplicating Next Day Air. Selecting either fails at UPS (120500);
   awaiting a data-owner decision. Ids 3/4 were coded by

package/knowledge/clients/nychh/INDEX.md

@@ -2,7 +2,8 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
-| [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 |
+| [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 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 |
 | [NYC Health & Hospitals](profile.md) | 2.0 | NYC Health & Hospitals (NYCHH) is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Nychh`. | dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql, dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.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

@@ -0,0 +1,172 @@
+---
+title: "NYCHH inventory-adjustment → item-fulfillment linking (custbody_stock_adjustment bridges)"
+framework: "1.0"
+repo: library
+project: Library
+client: nychh
+type: client-feature
+status: active
+updated: 2026-08-28
+owners: [jcardinal]
+files:
+  - 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
+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
+  - ../../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md
+  - ../profile.md
+---
+
+## Summary
+
+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.
+
+## 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:
+
+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):
+
+- **(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]`.
+
+## 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.
+
+```
+php crons/toga2/netsuite/diagnose_hh_import_inventory_adjustment.php <togaClient> <togaApi> <togaSecret> [adjustmentInternalId]
+```
+(creds = the `CLIENT_CONFIGURATION` client/api/secret from `sync_togasupply_hh.php`.)
+
+## 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.**
+
+## Known state — test adjustment 6516616
+
+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`).
+
+## 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`.
+- **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)

package/knowledge/clients/nychh/features/netsuite-transfer-order-import.md

@@ -6,7 +6,7 @@ project: Library
 client: nychh
 type: client-feature
 status: active
-updated: 2026-08-27
+updated: 2026-08-28
 owners: [jcardinal]
 files:
   - library/app/api/toga2.php
@@ -14,6 +14,10 @@ files:
   - 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
 related:
   - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
   - ../../../1.0/apps/library/features/toga2-api-client-and-bridge.md
@@ -114,6 +118,48 @@ status was previously throwing (and being swallowed), which is why order 128829
 `App_NetSuite::getCustomFieldValue()` (`library/app/netsuite.php`) was hardened with `?? []` / `?? null`
 guards: 1.0 targets PHP 7.2 and any PHP warning on that path terminates the cron.
 
+## SALES_ORDERS freeze chain — three distinct causes, peeled in order (2026-08-28)
+
+Once transfer-order routing was live, the NYCHH **and GroWrk** `SALES_ORDERS` section froze at
+`1-RUNNING` on `syncTransferOrderFromNetsuite`. `SALES_ORDERS` has **no per-record `try/catch`** (see
+[per-client sync](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md)), so any
+throw aborts the whole section and re-throws every run. Three separate faults sat one behind the next:
+
+1. **`Undefined property: stdClass::$transferOrderStage`** at the change-check in `toga2.php`
+   (`if ($transferOrder) {…}`). **api2 OMITS a null foreign-key object from a depth-2 GET entirely** —
+   it is *absent*, not null — so `$transferOrder->transferOrderStage` (and `originLocation` /
+   `destinationLocation`) raised a PHP warning that 1.0 `App_Error` escalates to fatal. **Fix:** guard
+   all three FK reads with `?? null`. (Lesson: on a depth-limited api2 GET, a nullable FK object may be
+   missing rather than null — always `?? null` before dereferencing.)
+2. **`EV-12` on the transfer-order-items POST** — the nested `transferOrder:{uuid}` link could not
+   resolve its parent because `RecordFields.uuid.isIdentifier` was **0** on records 312/313. Fixed
+   platform-wide (`dbchanges2/Core/2026-08-27a`). Full rule on the
+   [ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md).
+3. **MySQL 1054 `Unknown column 'dtCreated'` → api2 `EV-10`** one step further on.
+   `_Model_Client_TransferOrderItem` declares `dtCreated`/`dtUpdated`
+   (`FIELD_DATETIME_CREATED`/`_UPDATED`) and emits them on every INSERT, but the `TransferOrderItems`
+   **table lacked both columns in EVERY client DB** (a platform-wide drift — the header
+   `TransferOrders` table had them). **Fix (all-client, `dbchanges2/Client/` fan-out):** `2026-08-28a`
+   adds the two columns mirroring the header table (`DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP`,
+   `dtUpdated` also `ON UPDATE CURRENT_TIMESTAMP`); `2026-08-28b` repositions them (`AFTER uuid` /
+   `AFTER dtCreated`) per the new column-ordering standard —
+   [2.0 framework rules](../../../2.0/standards/framework-rules.md). Same failure class as GroWrk's
+   `_Model_Growrk_Unit` 1054: a declared model field with no physical column 1054s on every write.
+
+### Debugging lesson — `Logs.Issue` trace is stale; use a single-record harness for the real line
+
+`Logs.Issue` aggregates by message + runner and captures its `trace` **once at first-seen, never
+refreshed**. Issue 270's stale trace pointed at a bogus line and a spurious `$location` message and
+sent debugging the wrong way for a long time. The reliable way to get the true crash line was
+`worker/crons/toga2/netsuite/diagnose_hh_stuck_transfer_order.php` — a **manual operator tool** (not in
+`cron.worker.sync.json`; does **not** call `cronInitialization`, so no process lock / no cursor
+writes). It fetches a NetSuite sales/transfer order via `App_Api_Netsuite_Rest::listSalesOrders`
+(NYCHH entity filter `listChildCustomers(28908)`, window in server tz `America/Chicago`), dumps its
+shape, then re-runs the **real** `syncTransferOrderFromNetsuite` under a strict `set_error_handler`
+that rethrows warnings as a catchable `ErrorException` with exact `file:line`. That is what found the
+`transferOrderStage` crash after the stale `Logs.Issue` trace misdirected. **When a 1.0 cron freeze's
+`Logs.Issue` trace looks wrong, trust a single-record harness over the aggregated trace.**
+
 ## Gotchas / known issues
 
 - **Order 128829 (no location anywhere) is unresolved** — see the origin-resolution section. Do not
@@ -128,6 +174,17 @@ guards: 1.0 targets PHP 7.2 and any PHP warning on that path terminates the cron
 
 ## Change history
 
+- 2026-08-28 — Unfroze the `SALES_ORDERS` section (NYCHH + GroWrk) by peeling **three** stacked faults
+  on `syncTransferOrderFromNetsuite`: (1) `Undefined property $transferOrderStage` — api2 **omits a
+  null FK object** from a depth-2 GET, guarded `transferOrderStage`/`originLocation`/`destinationLocation`
+  with `?? null`; (2) `EV-12` because `RecordFields.uuid.isIdentifier` was 0 on records 312/313 (fixed
+  platform-wide, `dbchanges2/Core/2026-08-27a`); (3) MySQL 1054 → `EV-10` because `TransferOrderItems`
+  lacked the model-declared `dtCreated`/`dtUpdated` columns in every client DB (added all-client via
+  `dbchanges2/Client/2026-08-28a`, repositioned `AFTER uuid`/`AFTER dtCreated` per the new
+  column-ordering standard by `2026-08-28b`). Recorded the debugging lesson: `Logs.Issue`'s `trace` is
+  captured once and goes stale (Issue 270 misdirected), so a single-record harness
+  (`diagnose_hh_stuck_transfer_order.php`, strict `set_error_handler` → `ErrorException`) is the
+  reliable way to get the true crash line. (jcardinal)
 - 2026-08-27 — Built NYCHH transfer-order ingestion end-to-end. **Routing by `custbody_stocking_order`
   (id 7097), not dollar amount** (`isTransferOrder()` rewritten + new `isStockingOrder()` normalizer);
   the old `total===0 + hold-flag` heuristic was wrong for NYCHH (no hold flag set → everything landed

package/knowledge/clients/nychh/profile.md

@@ -33,6 +33,7 @@ related:
   - ./features/po-number-upstream-direction.md
   - ./features/netsuite-transfer-order-import.md
   - ./features/transfer-order-inventory-quantities.md
+  - ./features/netsuite-inventory-adjustment-fulfillment-link.md
   - ../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md
   - ../../2.0/apps/toga25-supply/features/transfer-orders-page.md
 ---
@@ -89,6 +90,11 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   fulfilled/backordered model on `_Model_Nychh_Item`, plus the client-override models + ACL rows that
   let a NetSuite TransferOrder POST succeed. See
   [NYCHH transfer-order inventory & quantities](./features/transfer-order-inventory-quantities.md).
+- **Inventory-adjustment → item-fulfillment linking** — imports NetSuite `custbody_stock_adjustment`
+  (adjustment→fulfillment) into two all-client bridges for adjustment→fulfillment→SO→PO traceability;
+  gated NYCHH-only, best-effort, with on-demand fulfillment import. Go-live toggle
+  (`IS_ENABLED_INTEGRATION_INVENTORY_ADJUSTMENTS`) still off. See
+  [NYCHH inventory-adjustment → item-fulfillment linking](./features/netsuite-inventory-adjustment-fulfillment-link.md).
 
 - **PO links are UPSTREAM (`PurchaseOrders_SalesOrders`), not downstream.** The downstream
   `sales-order-purchase-orders` route returns an empty array for NYCHH by design, and the shared

package/package.json

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