toga-ai 1.0.799 → 1.0.801

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-09-03
+updated: 2026-09-13
 owners: [dfranks, jcardinal, kyalamarthi, rgirish]
 files:
   - library/app/api/netsuite/rest.php
@@ -153,6 +153,42 @@ Forecast2 tables already store.
   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).
 
+- **The item-fulfillment shim now carries `orderLineUniqueKey` — the STABLE key for matching a
+  fulfillment line to its source order line (2026-09-13).** The fulfillment's `orderLine` (source
+  `linesequencenumber`) does **not** always equal the sales-order shim's displayed line, so
+  number-based matching in `syncItemFulfillmentFromNetsuite` silently missed. The shim derives
+  `orderLineUniqueKey` = the source order line's `transactionline.uniquekey`, via
+  `previoustransactionlinelink` joined to the source line with **`previousline IS NOT NULL`** (which
+  drops wash/inventory link rows). The importer matches it against TOGa
+  `SalesOrderItems.c_netsuiteLineUniqueKey`, falling back to the line-number path. Engine-side matcher
+  chain: [per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md).
+
+- **⚠ Package TRACKING NUMBERS need `?expandSubResources=true` — a bare package sub-resource GET
+  returns rows WITHOUT the fields, so tracking numbers never import (fixed 2026-09-13).**
+  `fetchItemFulfillmentById` fetched packages via a **bare** `GET /record/v1/itemFulfillment/{id}/package`,
+  which returns package rows **without** `packageTrackingNumber` inlined (proven: items come back as
+  `{links:[]}`) — so NYCHH bridges 317/318/319 stayed empty. **Fix:** fetch
+  `/record/v1/itemFulfillment/{id}/package?expandSubResources=true` (inlines the fields, scoped to
+  `/package` so the huge serial sublists are NOT pulled); only if the generic `package` sublist has no
+  tracking number, also check the carrier sublists
+  `/packageUps|packageFedex|packageUsps?expandSubResources=true`; dedupe by tracking number; and
+  **FAIL LOUD if the fetch fails** — a non-object/error body must not read as zero packages, which
+  would drop the number and advance the cursor. Verified end-to-end on a serialized IF: one NetSuite
+  tracking number fans to the header (317), the item (318), and all serial units (319). Fan-out
+  engine detail: [per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md).
+
+- **⚠ Three REST sub-resource gotchas (framework-level — apply to any `App_Api_Netsuite_Rest`
+  sub-resource fetch):**
+  1. **A bare sub-resource GET returns rows WITHOUT their fields.** Add `?expandSubResources=true` to
+     inline them (this is exactly what hid the package tracking numbers above).
+  2. **`fields=` and `expandSubResources` CANNOT be combined** — NetSuite returns **HTTP 400
+     `INVALID_PARAMETER` "not allowed in one request"**. Pick one per call.
+  3. **api2 truncates a large nested child collection (observed cap 25).** Never trust a single nested
+     GET's count — read the collection **flat and fully paginated** (`meta->nextPage`). This is the
+     shim-consumer side of the api2 truncation trap on the
+     [toga2 client doc](toga2-api-client-and-bridge.md); it drove the two flat-fetch helpers in the
+     fulfillment reconcile.
+
 - **`fetchPurchaseOrderById()` omitted `entity` from its SELECT and never set `$shim->entity` — so
   every PO shim had a null vendor and the fail-loud guard fired every run (2026-08-29).** Unlike its
   sibling `listPurchaseOrders` (which DOES select `entity` + `BUILTIN.DF(entity)` and populates the
@@ -323,6 +359,20 @@ None — uniform across clients (NetSuite is a single shared account).
 
 ## Change history
 
+- 2026-09-13 — **Item-fulfillment shim gotchas from the NYCHH ITEM_FULFILLMENTS unfreeze (library,
+  deployed + verified).** (1) The item-fulfillment REST shim now carries **`orderLineUniqueKey`** (the
+  source line's `transactionline.uniquekey`, via `previoustransactionlinelink` joined to the source
+  line, `previousline IS NOT NULL` to drop wash/inventory lines) so the importer can match a
+  fulfillment line by a stable key instead of the drifting line number. (2) **Package tracking numbers
+  never imported** because `fetchItemFulfillmentById` fetched `/package` **bare** (no fields inlined);
+  fixed to `?expandSubResources=true` scoped to `/package`, falling back to the carrier sublists
+  (`packageUps|packageFedex|packageUsps`), deduped by tracking number, and **fail-loud** if the fetch
+  errors so a bad body is not read as zero packages. (3) Recorded three framework-level REST
+  sub-resource gotchas: a bare sub-resource GET omits fields (`expandSubResources=true` inlines them);
+  `fields=` and `expandSubResources` cannot be combined (HTTP 400 `INVALID_PARAMETER`); and api2
+  truncates a large nested child collection (cap ~25) so read it flat + fully paginated. Engine-side
+  reconcile detail: [per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md).
+  (jcardinal)
 - 2026-09-03 — Documented that a sales-order shim's **`->holdInvoice` is not a native NetSuite
   field**: it is normalised inside the shim from the custom checkbox **`custbody_asi_hold` (id
   4082)**, which is **shared across all clients** ("asi" = Agilant Solutions Inc, not a client

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-09-11
+updated: 2026-09-13
 owners: [jcardinal, mhammontree, bala]
 files:
   - library/app/api/toga2.php
@@ -331,7 +331,13 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
   is silently wrong. **Read the collection flat and fully paginated** (query the child resource
   directly with the universal `meta->nextPage` loop) and take counts from **`meta.totalRecordCount`**,
   not from a single nested response. Surfaced building the NYCHH fulfillment asset-tag verifier
-  (`worker/crons/toga2/netsuite/verify_fulfillment_asset_tag_sync_nychh.php`).
+  (`worker/crons/toga2/netsuite/verify_fulfillment_asset_tag_sync_nychh.php`). **Confirmed again on
+  the fulfillment reconcile (2026-09-13):** the `salesOrderItems` nested collection truncated at
+  **25**, and a fulfillment's `itemFulfillmentItemUnits` re-created 25,766 links for 1,192 real units.
+  The reconcile now reads both flat + fully paginated via two new private helpers,
+  `getItemFulfillmentItemUnitsByItemFulfillmentUuid()` and `getSalesOrderItemsBySalesOrderUuid()`
+  (`recordsPerPage` 1000, page-cap 500, `nextPage ?? null`) — detail on the
+  [per-client sync doc](../../worker/features/netsuite-togasupply-per-client-sync.md).
 - **🔐 Hardcoded credentials.** Every client's `CLIENT_UUID_*`, `API_UUID_*`, and `API_SECRET_*`
   (plus the "True Workers" master keys) are committed as plaintext class constants at the top of
   `toga2.php`. Treat them as **compromised-if-leaked**; do not reproduce the values in the KB,
@@ -424,6 +430,14 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
 
 ## Change history
 
+- 2026-09-13 — Two new private helpers on this class read a nested collection **flat + fully
+  paginated** to dodge the api2 nested-GET truncation:
+  `getItemFulfillmentItemUnitsByItemFulfillmentUuid()` and `getSalesOrderItemsBySalesOrderUuid()`
+  (both feed the fulfillment reconcile). Recorded the fresh evidence — `salesOrderItems` truncated at
+  **25**, and one fulfillment re-created 25,766 unit links for 1,192 real units. The methods and the
+  full five-bug ITEM_FULFILLMENTS unfreeze live on the
+  [per-client sync doc](../../worker/features/netsuite-togasupply-per-client-sync.md) (these are
+  `*FromNetsuite` importer internals, scoped there per this doc's Summary). (jcardinal)
 - 2026-09-11 — **Observability: `send()`'s "Invalid API Response" exception now leads with the api2
   message codes.** Added a private `describeApiMessages()` helper (~L726) that renders the
   `->messages[].code: text` list (each text capped at 160 chars, cso point) and prepended it to the

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-09-11
+updated: 2026-09-13
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -583,6 +583,57 @@ the [Quad profile](../../../clients/quad/profile.md) and the
 Design rationale for putting this at the source writer rather than a 317 interceptor lives on the
 [recursive item fulfillments doc](../../../2.0/apps/_underscore/features/recursive-item-fulfillments.md).
 
+### Fulfillment line → sales-order line matching is a 4-step chain (2026-09-13)
+
+The fulfillment matcher in `syncItemFulfillmentFromNetsuite` resolves each fulfillment line back
+to its `SalesOrderItems` / `TransferOrderItems` parent. It tries, in order, and stops at the first
+hit:
+
+1. **Stable unique key (preferred).** The item-fulfillment REST shim now carries
+   `orderLineUniqueKey` — the source order line's `transactionline.uniquekey`, derived via
+   `previoustransactionlinelink` joined to the source line (`previousline IS NOT NULL`, which drops
+   wash/inventory lines). The matcher compares it to TOGa `SalesOrderItems.c_netsuiteLineUniqueKey`.
+   This replaces number-based matching as the primary key because the fulfillment's `orderLine`
+   (source `linesequencenumber`) does **not** always equal the sales-order shim's displayed line, so
+   number matching silently missed. Shim detail:
+   [SuiteQL/REST shim](../../library/features/netsuite-suiteql-rest-shim.md).
+2. **Line number** — the old path, kept as a fallback.
+3. **Reconstruct** — the existing rebuild path.
+4. **Part number (last resort).** Match by part number (UPPER + trim) **only when exactly ONE** SO
+   line carries that part number — it never guesses between duplicates, and it **consumes** the
+   matched line so a repeat cannot reuse it. This exists because some fulfillment lines'
+   `previoustransactionlinelink` points at a **TAX line** (TaxGroup, item −8 "−Not Taxable−") instead
+   of the product line, so unique-key + line-number + reconstruct all miss even though the product IS
+   on the SO.
+
+**An unmatched line FAILS LOUD (throws) — it never creates an orphan.** When no parent resolves the
+code used to still create an item-fulfillment-item with **NULL** `salesOrderItemId` AND
+`transferOrderItemId`. That row can never be matched next run, so a fresh orphan was created every
+run and units split under it (runaway growth the unit-dedup cannot see because it is cross-item).
+Now it throws; the section stays `RUNNING` for a human, matching the fail-loud policy (worker
+stdout/`error_log` is discarded, so a silent skip is invisible). A self-heal deletes existing
+null-parent items on sight: each item's units → each unit's tracking bridge → the unit → the item's
+tracking → the item.
+
+### Nested-GET truncation drives two flat + paginated helpers (2026-09-13)
+
+api2 **silently truncates a large nested child collection** returned inside one parent GET (see the
+truncation gotcha on the [toga2 client doc](../../library/features/toga2-api-client-and-bridge.md)),
+which corrupted the fulfillment reconcile in two places. Both now read the collection **flat and
+fully paginated** (`recordsPerPage` 1000, page-cap 500, `nextPage ?? null`) instead of trusting the
+nested count:
+
+- **Existing units for the dedup map** — `getItemFulfillmentItemUnitsByItemFulfillmentUuid()`. The
+  dedup map used to be built from the nested `itemFulfillmentItem->itemFulfillmentItemUnits` in one
+  `GET /item-fulfillments`; units it did not see were re-created every run (prod: **25,766** unit
+  links for **1,192** real units on one fulfillment, section frozen). A **self-heal** deletes
+  duplicate unit links, keeping one per item + `assignmentId` and removing the tracking-bridge
+  children first (FK `RESTRICT`).
+- **Sales-order items for the matcher** — `getSalesOrderItemsBySalesOrderUuid()`. The matcher's SO
+  fetch returned `salesOrderItems` truncated (observed cap **25**); an order with >25 lines dropped a
+  line the fulfillment referenced, the match failed, and the section fail-loud-froze. The flat list
+  replaces the truncated nested one before match/reconstruct.
+
 ### Custom field contract (hardcoded in `common_sync_togasupply.php`)
 
 The engine requests these `c_` fields by literal name per route — every synced client must have
@@ -1482,6 +1533,26 @@ library (or vice versa) crashes GroWrk and Adyen on their next sync run.
 
 ## Change history
 
+- 2026-09-13 — **ITEM_FULFILLMENTS unfrozen for NYCHH: five stacked fulfillment-reconcile bugs fixed
+  (library, deployed + verified in prod).** (1) **Unit duplication from a truncated nested GET** — the
+  existing-units dedup map was built from the nested `itemFulfillmentItemUnits` of one
+  `GET /item-fulfillments`, which api2 silently truncates, so unseen units re-created every run
+  (**25,766** unit links for **1,192** real units on one fulfillment). New
+  `getItemFulfillmentItemUnitsByItemFulfillmentUuid()` reads units flat + fully paginated
+  (`recordsPerPage` 1000, page-cap 500, `nextPage ?? null`) and drives the dedup; a self-heal deletes
+  duplicate unit links (keep one per item + `assignmentId`, tracking-bridge children first for FK
+  RESTRICT). (2) **Orphan item-fulfillment-items** — an unresolved line used to create an item with
+  NULL `salesOrderItemId` AND `transferOrderItemId`, un-matchable so a fresh orphan spawned every run;
+  now **fails loud** (throws) and a self-heal deletes existing null-parent items (units → tracking
+  bridge → unit → item tracking → item). (3) **SO-items nested truncation (cap 25)** — new
+  `getSalesOrderItemsBySalesOrderUuid()` reads all SO items flat + paginated, replacing the truncated
+  nested list before match/reconstruct. (4) **Match on the stable unique key** — the shim now carries
+  `orderLineUniqueKey` and the matcher prefers it over the line number (falls back to number →
+  reconstruct). (5) **Part-number fallback** — last-resort match by part number (UPPER+trim) only when
+  exactly ONE SO line carries it (consumes the line; never guesses between duplicates), for lines whose
+  `previoustransactionlinelink` points at a TAX line. Shim-side detail (`orderLineUniqueKey`, package
+  tracking) on the [SuiteQL/REST shim](../../library/features/netsuite-suiteql-rest-shim.md). An
+  unmatched line fails loud, consistent with the 2026-08-27 policy. (jcardinal)
 - 2026-09-11 — **ITEM_RECEIPTS froze at RUNNING on NYCHH: a case-mismatched `Units` serial lookup
   (library, fix written not deployed).** `syncItemReceiptFromNetsuite` (`library/app/api/toga2.php`
   ~L4022) keyed a PHP existing-`Units` array on the DB's stored serial casing (`'na100'`) but read it

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-09-10
+updated: 2026-09-13
 owners: [jcardinal, bala, rgirish]
 files:
   - library/app/api/toga2.php
@@ -122,6 +122,15 @@ full evidence table (location 75 → warehouse 117, the only `allowSending` sour
 locations carry a customer id, 7 carry a location id) is in
 [NYCHH TransferOrder → NetSuite push](./transfer-order-netsuite-push.md).
 
+> **⚠ OPEN, not fixed (2026-09-13) — a transfer order's DESTINATION location does not resolve, and
+> it is now collapsing the INVENTORY_ADJUSTMENTS section.** `TransferOrders.destinationLocationId` is
+> also NOT NULL. The INVENTORY_ADJUSTMENTS section (window shrinking, stuck `RUNNING`) runs an
+> on-demand cascade that imports a transfer-order-backed fulfillment, and the
+> `POST /v2/transfer-orders` for **TO 277871** (`c_netsuiteInternalSalesOrderId` **7102750**) fails
+> **EV-10 "Column 'destinationLocationId' cannot be null"** — the **origin** resolved but the
+> **destination** did not. This is a **separate** destination-resolution bug from the origin
+> fallback above (and from the 128829 no-location edge case). Next task; not yet root-caused.
+
 ## Item-fulfillment transfer-order line link
 
 `ItemFulfillmentItems.transferOrderItemId` must populate so the 2.0 stock-out quantity calc can tie
@@ -315,6 +324,12 @@ item receipts replays about two years unless it is rewound forward first.
 
 ## Change history
 
+- 2026-09-13 - **OPEN: INVENTORY_ADJUSTMENTS collapsing on an unresolved transfer-order
+  DESTINATION.** The section's on-demand cascade imports a transfer-order-backed fulfillment, and
+  `POST /v2/transfer-orders` for **TO 277871** (`c_netsuiteInternalSalesOrderId` **7102750**) fails
+  **EV-10 "Column 'destinationLocationId' cannot be null"** — origin resolved, destination did not.
+  Separate from the origin fallback and the 128829 no-location case; next task, not yet root-caused.
+  Recorded in the origin/destination section. (jcardinal)
 - 2026-09-10 - Recorded that the import concentrates **1,832 of 1,939** transfer orders on catch-all
   destination **location 2**, all with `createdByUserId` NULL (so none came from the Create Transfer
   Order screen), and that whether it should resolve the real hospital instead is still open with the

package/knowledge/clients/nychh/profile.md

@@ -18,7 +18,7 @@ project: _Underscore
 client: nychh
 type: profile
 status: active
-updated: 2026-09-11
+updated: 2026-09-13
 owners: ["jcardinal", "apeterson", "bala", "akhokhani"]
 files:
   - dbchanges2/Client_Nychh/2026-09-02a - TransferOrderNetsuitePushInterceptor.sql
@@ -125,6 +125,25 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   (`strtoupper()` on both the key and the reads). This is a **different** duplicate from the open
   sales-order `Items` duplicate below (658-BFZH). Mechanism + the EV-10 → `Logs_Nychh.Api` diagnosis
   traps: [per-client sync doc](../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
+- **ITEM_FULFILLMENTS freeze RESOLVED — five stacked reconcile bugs fixed, deployed + verified
+  (2026-09-13).** The frozen section (prod: 25,766 unit links for 1,192 real units on one fulfillment)
+  is cleared: (1) unit dedup now reads existing units **flat + fully paginated** instead of from a
+  truncated nested GET; (2) an unmatched fulfillment line **fails loud** instead of creating a
+  never-matchable NULL-parent orphan (self-heal deletes existing orphans); (3) the SO-items fetch is
+  flat + paginated (api2 truncated the nested list at 25); (4) fulfillment→SO line matching prefers the
+  stable `orderLineUniqueKey` over the drifting line number; (5) a part-number last-resort match for
+  lines whose NetSuite link points at a TAX line. **Package tracking numbers now import to all three
+  bridges (317/318/319)** — the shim fetches `/package?expandSubResources=true` (a bare sub-resource
+  GET returned no fields), so one NetSuite tracking number fans to the header, item, and every serial
+  unit. Engine + shim detail:
+  [per-client sync](../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md),
+  [SuiteQL/REST shim](../../1.0/apps/library/features/netsuite-suiteql-rest-shim.md).
+- 🚩 **OPEN (2026-09-13): INVENTORY_ADJUSTMENTS collapsing on an unresolved transfer-order
+  DESTINATION.** The section's on-demand cascade imports a transfer-order-backed fulfillment and
+  `POST /v2/transfer-orders` for **TO 277871** (`c_netsuiteInternalSalesOrderId` 7102750) fails
+  **EV-10 "destinationLocationId cannot be null"** — origin resolved, destination did not. Separate
+  destination-resolution bug; next task. See
+  [NYCHH NetSuite → TransferOrders import](./features/netsuite-transfer-order-import.md).
 - **NYCHH sync scope + data-gap scale + backfill approach (2026-09-09).**
   - **Scope = 22 NetSuite customers:** parent **28908** "NYC Health + Hospitals" + 21 hospital child
     customers (`24145, 29273, 29276, 31584, 31910-31916, 31918-31925, 32229, 33674`).

package/package.json

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

package/rules/common/communication.md

@@ -51,6 +51,44 @@ What you need to do:
 4. Confirm the WorkerJobs table shows the new column.
 ```
 
+## Cut output tokens — the safe way
+
+Shorter answers are clearer AND cheaper to run. Both matter. But **clarity always wins** —
+every rule here stops the moment it would make you harder to understand. This sharpens the
+rules above; it never overrides them.
+
+**Drop these words — they add length, not meaning:**
+
+- Filler: just, really, basically, actually, simply.
+- Pleasantries: sure, certainly, of course, happy to, great question.
+- Hedging: I think, it seems, perhaps, kind of, sort of.
+
+Say it straight. "Basically you just need to..." → "You need to...".
+
+**Keep these exact — never shorten:**
+
+- Numbers, and negation words: not, never, no, only, except. Flipping one changes the
+  meaning — never worth a saved word.
+- Code, commands, file names, and error text — word for word. Do not compress or reword them.
+
+**Do not narrate your tool use.** Skip "Now I'll read the file", "Let me check", "I'm going
+to run...". Do the work, then report the result.
+
+**Do not dump long output — quote the shortest line that proves the point.** For a long log
+or stack trace, paste the one decisive line and name the file for the rest. A wall of raw log
+buries the finding.
+
+**Do not decorate:**
+
+- No emoji as decoration.
+- No table when one sentence does the job. Use a table only for real rows and columns.
+- No made-up short forms (cfg, impl, req). The tokenizer splits them the same as the full
+  word, so you save nothing and the reader still has to decode.
+
+**Write it out in full — normal prose — where being terse causes mistakes:** the numbered
+manual steps above (deploys, SQL, config, restarts), security warnings, and anything hard to
+undo. Clarity wins there, every time.
+
 ## Check before you send
 
 - Can I cut half the words and keep the meaning? Cut them.

package/scripts/hooks/plain-talk.js

@@ -51,6 +51,9 @@ function reminder() {
     '     say what it means in plain words instead. Stay exact — keep file names, errors, steps.',
     '  4. Any manual action (deploy, SQL, config, restart) goes in a numbered list under a',
     '     "What you need to do:" heading. One action per step, in order.',
+    '  5. Trim output: drop filler/pleasantries/hedging, no tool-use narration, quote the',
+    '     shortest decisive log line (not the whole dump), no decorative tables/emoji. Keep',
+    '     numbers, negations, code, and errors exact. Clarity always wins over shortness.',
     '',
     'MIRROR THIS PERSON: read how the developer writes to you in this session — the words',
     'and phrases they use, and how long their sentences run — and answer back in that same',