toga-ai 1.0.699 → 1.0.701

package/knowledge/1.0/apps/library/INDEX.md

@@ -14,6 +14,7 @@
 | [Error Capture in 1.0 (App_Error_Capture → shared 2.0 Logs DB)](features/error-capture-1-0.md) | The 1.0 side of the platform error-reporting pipeline (TRUE-78188). | library/app/error/capture.php, library/app/error.php, library/app/exception/business.php, library/app/api/toga2.php, library/app/cloud.php, worker/config.worker.ini, worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php |
 | [HTTP 500 Error Monitor (App_SystemMonitor_500Error) — and why its \"Error Type\" is not a diagnosis](features/http-500-error-monitor.md) | `App_SystemMonitor_500Error` (`library/app/systemmonitor/500error.php`, title **"HTTP 500 Error Alert"**) is the 1.0 system monitor that watches **`Logs.Api` fo | library/app/systemmonitor/500error.php, worker/crons/infrastructure/system_monitors.php, api2/Controller/Index.php, _underscore/Error.php |
 | [1.0 MVC Page Pattern & New-App Skeleton](features/mvc-page-pattern-and-app-skeleton.md) | This is the **reusable recipe for standing up a new 1.0 (`App_`) application** and for adding pages to one — the folder-based MVC routing, the page lifecycle, t | library/app/framework.php, library/app/frameworkindex.php, library/app/mvc.php, library/app/database.php, library/app/model.php, library/app/config.php |
+| [NetSuite File Cabinet Content Retrieval via RESTlet (fetchInvoiceFile)](features/netsuite-filecabinet-restlet.md) | How 1.0 pulls **File Cabinet binary content** (invoice PDFs) out of NetSuite over REST. | library/app/api/netsuite/rest.php, worker/crons/toga2/netsuite/netsuite_restlet_filecontent.js, worker/config.worker.ini |
 | [isFulfillable from NetSuite during Item Sync (Phase 1)](features/netsuite-item-isfulfillable-sync.md) | This is the **1.0 (Phase 1)** half of the `isFulfillable` feature: reading the NetSuite `isfulfillable` flag during item sync and stamping it onto the **Agilant | library/app/netsuite.php, library/app/api/toga2.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/backfill_isfulfillable_jul5.php |
 | [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | General working reference for the Agilant NetSuite integration: how to authenticate, how SuiteQL behaves, and the confirmed schema of the tables/columns/codes w | library/app/api/netsuite/rest.php, library/ssl/netsuite_ec_key.pem, test/@dave/Junk Drawer/nsq.php |
 | [NetSuite SuiteQL/REST Shim — Field Semantics](features/netsuite-suiteql-rest-shim.md) | `App_Api_Netsuite_Rest` is the REST/SuiteQL replacement for the deprecated NetSuite SOAP toolkit. | library/app/api/netsuite/rest.php, library/app/netsuite.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |

package/knowledge/1.0/apps/library/features/netsuite-filecabinet-restlet.md

@@ -0,0 +1,122 @@
+---
+title: NetSuite File Cabinet Content Retrieval via RESTlet (fetchInvoiceFile)
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-08-29
+owners: [jcardinal]
+files:
+  - library/app/api/netsuite/rest.php
+  - worker/crons/toga2/netsuite/netsuite_restlet_filecontent.js
+  - worker/config.worker.ini
+related:
+  - netsuite-suiteql-api-reference.md
+  - netsuite-suiteql-rest-shim.md
+  - ../../worker/features/netsuite-togasupply-per-client-sync.md
+---
+
+## Summary
+
+How 1.0 pulls **File Cabinet binary content** (invoice PDFs) out of NetSuite over REST. The
+short version: **there is no token-only, code-only REST path to File Cabinet binary content in
+this account.** The `/record/v1/file` Record Service is not enabled, SuiteQL exposes only file
+*metadata* (no content column), and the `media.nl` UI URL is not fetchable with an OAuth token.
+The only REST mechanism is a **SuiteScript 2.1 RESTlet** that loads the file server-side and
+returns its bytes base64-encoded. `App_Api_Netsuite_Rest::fetchInvoiceFile()` uses exactly that.
+
+This replaced the SOAP `App_NetSuite::getInvoiceFile` as part of completing the SOAP→REST
+migration of the togasupply sync path (see the
+[per-client-sync doc](../../worker/features/netsuite-togasupply-per-client-sync.md)).
+
+## Why there is no token-only REST path (verified live, 2026-08-29)
+
+Three routes were probed against this account and all three are dead ends for binary content:
+
+- **REST Record Service `GET /record/v1/file/{id}` → HTTP 404 `NONEXISTENT_ID`**, *"Record type
+  'file' does not exist."* The `file` record type is simply not in this account's REST Record
+  Service. (The earlier `fetchInvoiceFile` design assumed this endpoint worked — it never did.)
+- **SuiteQL `file` table exposes ONLY metadata** — `id, name, filetype, filesize, folder, url,
+  createddate, lastmodifieddate` and `is*` flags. There is **no binary/content column**. Good for
+  *finding* the file id by name; useless for its bytes.
+- **The SuiteQL `url` is a `media.nl` UI link, not an API resource.** It is a
+  `/core/media/media.nl?...&c=<acct>&h=<hash>` link on the `<acct>.app.netsuite.com` **UI domain**.
+  Fetching it — anonymous OR with an OAuth Bearer — is rejected (redirects to `page_not_found`),
+  because invoice PDFs are **not** flagged "Available Without Login" and the OAuth token does not
+  authorize the UI media servlet.
+
+Conclusion: to get File Cabinet bytes over REST you must run server-side script. That is the
+RESTlet.
+
+## How it works
+
+### NetSuite side — the RESTlet
+
+`worker/crons/toga2/netsuite/netsuite_restlet_filecontent.js` is a **SuiteScript 2.1 RESTlet**
+that does `N/file.load(id).getContents()` and returns the content **base64-encoded**. Deployed in
+NetSuite as script **`customscript2829`** / deployment **`customdeploy1`** (non-secret identifiers),
+with the **RESTlets** OAuth scope enabled on the **"TOGA OAuth 2.0"** integration record.
+
+### Client side
+
+- **`App_Api_Netsuite_Rest::callRestlet()`** — GETs
+  `<acct>.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script=<id>&deploy=<id>` (note the
+  **`restlets.api.netsuite.com`** host, distinct from the SuiteQL/REST `suitetalk` host).
+- **`fetchInvoiceFile()`** — SuiteQL `file`-table lookup by name to get the file **id** →
+  `callRestlet()` → `base64_decode()` → raw bytes. **Fail-loud preserved:** no file row → `null`;
+  a file found but unretrievable, or a RESTlet error → **throws** (never silently returns empty).
+- **Config:** the script/deploy ids live in `worker/config.worker.ini` `[netsuite]` as
+  `restletScriptId` / `restletDeployId`.
+
+### Validated byte-identical to SOAP
+
+RESTlet-retrieved PDFs were confirmed **byte-identical** (matching length + md5) to what SOAP
+`getInvoiceFile` returned, across 3 Compass invoices (~265 KB each). Zero `fetchInvoiceFile` /
+`INVALID_LOGIN` errors after deploy. This also unblocked Endeavor Health's whole pipeline — its
+INVOICES section had been throwing on the broken file fetch and collateral-freezing
+IR/IF/InvAdj.
+
+## Gotchas / known issues
+
+- **⚠ NetSuite issues ONE active OAuth 2.0 token per client credential — a second token with a
+  DIFFERENT scope INVALIDATES the first.** Fetching a separately-scoped `restlets` token caused the
+  very next SuiteQL call to fail with **HTTP 400 `INVALID_LOGIN`**. **Fix: request ONE
+  combined-scope token** — a single `OAUTH_SCOPE` of `rest_webservices restlets` — never two
+  separate tokens. This requires the **RESTlets scope enabled on the integration record**. The
+  initially-tried "isolated separate restlets token" design is what caused the `INVALID_LOGIN` and
+  was removed. (This is a general OAuth fact: any future added scope must be folded into the single
+  combined-scope request, not fetched as a second token.)
+- **⚠ A RESTlet whose function returns an object requires the REQUEST to carry
+  `Content-Type: application/json`** — otherwise NetSuite rejects it with HTTP 400
+  `INVALID_RETURN_DATA_FORMAT` (*"Invalid data format. You should return text."*). Set the request
+  content type even though `callRestlet` is a GET with no meaningful body.
+- **PHP 7.2 prod constraint** applies to `rest.php` as everywhere — lint with
+  `C:\xampp7\php\php.exe -l` before deploying (a single 7.4+ token parse-errors the whole class;
+  see the [api reference](netsuite-suiteql-api-reference.md) blast-radius gotcha).
+
+## Change history
+
+- 2026-08-29 — Created. Migrated invoice-PDF retrieval off SOAP `getInvoiceFile` to a SuiteScript
+  2.1 RESTlet (`customscript2829`/`customdeploy1`) after verifying live that **no token-only REST
+  path to File Cabinet binary exists** in this account: `/record/v1/file/{id}` 404s
+  (`NONEXISTENT_ID`, file record not in the REST Record Service), SuiteQL `file` is metadata-only
+  (no content column), and the `media.nl` UI url is not OAuth-fetchable. Added
+  `App_Api_Netsuite_Rest::callRestlet()` + rewrote `fetchInvoiceFile` (SuiteQL id lookup →
+  callRestlet → base64_decode, fail-loud). Recorded two RESTlet/OAuth gotchas: one active token per
+  client credential so scopes must be combined (`rest_webservices restlets` in a single request,
+  else the next SuiteQL call 400s `INVALID_LOGIN`), and an object-returning RESTlet needs request
+  `Content-Type: application/json` (else 400 `INVALID_RETURN_DATA_FORMAT`). RESTlet PDFs verified
+  byte-identical to SOAP across 3 Compass invoices; unblocked Endeavor Health's pipeline. (jcardinal)
+
+## Related docs
+
+- [`netsuite-suiteql-api-reference.md`](netsuite-suiteql-api-reference.md) — auth (OAuth2/JWT),
+  SuiteQL mechanics, the `fetch*ById()` helper family that `fetchInvoiceFile` belongs to.
+- [`netsuite-suiteql-rest-shim.md`](netsuite-suiteql-rest-shim.md) — REST-shim field/shape
+  semantics.
+- [per-client-sync](../../worker/features/netsuite-togasupply-per-client-sync.md) — the togasupply
+  engine whose INVOICES section consumes `fetchInvoiceFile`.
+</content>
+</invoke>

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

@@ -14,6 +14,7 @@ files:
   - test/@dave/Junk Drawer/nsq.php
 related:
   - netsuite-suiteql-rest-shim.md
+  - netsuite-filecabinet-restlet.md
   - ../architecture.md
   - ../../worker/features/forecast2-netsuite-reconciliation.md
   - ../../../clients/nychh/features/netsuite-inventory-adjustment-fulfillment-link.md
@@ -42,6 +43,12 @@ This doc is the **broad map** (mechanics, schemas, codes, performance). For the
   a placeholder `CERTIFICATE_ID_HERE` that `initialize()` explicitly rejects.
 - `readConfig()` supports two framework contexts: 1.0 via `App_Registry::get('config')['netsuite']`,
   and 2.0 via `_Config::netsuite()`.
+- **⚠ ONE active OAuth token per client credential — combine scopes, never fetch a second token.**
+  NetSuite invalidates the first token when a second is requested with a *different* scope: after a
+  separately-scoped `restlets` token was fetched, the next SuiteQL call 400'd `INVALID_LOGIN`. Request
+  a single combined `OAUTH_SCOPE` (currently `rest_webservices restlets`, the latter enabled on the
+  "TOGA OAuth 2.0" integration for `fetchInvoiceFile`). Any future scope must be folded into this one
+  request. See [File Cabinet content via RESTlet](netsuite-filecabinet-restlet.md).
 
 ## Bootstrapping the client from a standalone script
 
@@ -365,8 +372,13 @@ exclusively — zero `App_NetSuite::` SOAP network calls remain** in `common_syn
 - **`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`.
+- **`fetchInvoiceFile`** — SuiteQL `file`-table lookup for the id → **RESTlet** call
+  (`callRestlet()`) → `base64_decode` → raw bytes. Replaces SOAP `getInvoiceFile`. **NOT** a REST
+  record GET — `GET /record/v1/file/{id}` 404s (`NONEXISTENT_ID`; the `file` record is not in this
+  account's REST Record Service), SuiteQL `file` is metadata-only, and the `media.nl` url is not
+  OAuth-fetchable, so a SuiteScript RESTlet is the only REST path to File Cabinet binary. Full
+  mechanics + the two OAuth/RESTlet gotchas: [File Cabinet content via
+  RESTlet](netsuite-filecabinet-restlet.md).
 
 `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
@@ -442,6 +454,14 @@ numbers. Budget hours for multi-year runs and launch them under `nohup`/`tmux`.
 
 ## Change history
 
+- 2026-08-29 — Corrected `fetchInvoiceFile` (deploy/verify session): it is **RESTlet-based**, not a
+  REST record GET — `GET /record/v1/file/{id}` 404s (`file` record not in this account's REST Record
+  Service), SuiteQL `file` is metadata-only, `media.nl` isn't OAuth-fetchable, so a SuiteScript 2.1
+  RESTlet is the only REST path to File Cabinet binary; new
+  [File Cabinet content via RESTlet](netsuite-filecabinet-restlet.md) doc holds the mechanics. Added the
+  **one-active-token-per-credential** auth rule to Authentication (combine scopes into a single
+  `rest_webservices restlets` request; a separate second token 400s the next SuiteQL call
+  `INVALID_LOGIN`). (jcardinal)
 - 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,

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

@@ -122,6 +122,40 @@ 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).
 
+- **`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
+  shim's vendor), `fetchPurchaseOrderById`'s SuiteQL header query left `entity` out and the shim never
+  built `$shim->entity`. The item-receipt path (`syncItemReceiptFromNetsuite` →
+  `syncPurchaseOrderFromNetsuite`) therefore always saw a null entity, and the fail-loud guard
+  `if (empty($nsPurchaseOrder->entity)) throw 'has no vendor/entity'` threw on **every** run — freezing
+  **Canon** and **Endeavor Health** ITEM_RECEIPTS at `1-RUNNING` (window collapsed ÷3 to 1s), watermarks
+  frozen ~8 and ~5 days. **Fix:** added `entity, BUILTIN.DF(entity) AS entity_name` to the header SELECT
+  and populated `$shim->entity` as `{internalId, name}` (matching the other shims); a genuinely
+  vendorless PO still throws. Same class as the `tl.location` regression below and the missing-entity
+  guard was correct — the SELECT was the defect. **When adding a shim, every field the guard/consumer
+  reads must actually be in the SELECT.**
+  - **The entity fix was only the first of a chain — the real fix completed the shim to MATCH
+    `listPurchaseOrders`' FULL shape (deploy/verify session, 2026-08-29).** `syncPurchaseOrderFromNetsuite`
+    (reached via the item-receipt path) reads a whole set of PO properties **unguarded**, so each one the
+    `fetchPurchaseOrderById` shim omitted threw a 1.0 warning → `App_Error` `exit()` → froze the section —
+    an "entity → createdFrom → shippingAddress → customForm → tranId → tranDate → line/description/rate"
+    whack-a-mole, one missing field surfacing the next. Fixed by making the per-id shim reproduce the
+    sibling **list** shape exactly: added `entity` + `trandate` to the header SuiteQL, `tl.rate` + `tl.memo`
+    to the line query, and populated `createdFrom` / `shippingAddress` / `customForm` from the per-id REST
+    GET. **Lesson (sharper than "a field the consumer reads must be in the SELECT"): a REST shim consumed
+    by a SHARED sync method must reproduce the FULL sibling-`list*` shape — every header field, every line
+    field, every nested object — not just the fields the one path you are testing happens to read.** This
+    cleared Canon(12)/Endeavor(11) ITEM_RECEIPTS to IDLE.
+
+- **`buildSalesOrderShims()` / `fetchSalesOrderByIdFull()` SO-item shims now carry `createdPo` + `poRate`
+  (2026-08-29).** `syncPurchaseOrderFromNetsuite`'s SO-reconciliation loop reads
+  `$nsSalesOrderItem->createdPo` ({internalId}|null) and `$nsSalesOrderItem->poRate` (float|null)
+  **unguarded** — an `Undefined property $createdPo` → `exit()`. This loop was **newly reached** by the
+  `createdFrom` completion above, which is exactly how the next-missing-field surfaced. Both are now read
+  defensively from the per-id REST `salesOrder` sublist already fetched, so the SO-item shim matches what
+  the loop consumes. Same "reproduce the full sibling shape" class as the PO-shim completion.
+
 - **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
@@ -215,6 +249,25 @@ None — uniform across clients (NetSuite is a single shared account).
 
 ## Change history
 
+- 2026-08-29 — **Completed `fetchPurchaseOrderById` to the full `listPurchaseOrders` shape** and added
+  the SO-item `createdPo`/`poRate` shim fields (same deploy/verify session, after the entity fix). The
+  entity SELECT was only the first missing field: `syncPurchaseOrderFromNetsuite` reads `createdFrom`,
+  `shippingAddress`, `customForm`, `tranId`, `tranDate`, and line `rate`/`description` unguarded, so each
+  omission threw in turn (whack-a-mole). Fixed by matching the sibling **list** shape exactly (header:
+  `entity`+`trandate`; line: `tl.rate`+`tl.memo`; populated `createdFrom`/`shippingAddress`/`customForm`
+  from the per-id REST GET). Completing `createdFrom` newly reached the SO-reconciliation loop, exposing
+  the next unguarded reads `$nsSalesOrderItem->createdPo`/`poRate` — now carried on the
+  `buildSalesOrderShims`/`fetchSalesOrderByIdFull` SO-item shims (read from the per-id REST `salesOrder`
+  sublist). Lesson: a shim consumed by a shared sync method must reproduce the FULL sibling-list shape,
+  not the fields the tested path happens to read. (jcardinal)
+- 2026-08-29 — Recorded `fetchPurchaseOrderById()`'s **missing `entity` SELECT** (deploy/verify
+  session): its header query omitted `entity`/`BUILTIN.DF(entity)` and the shim never set
+  `$shim->entity` (unlike `listPurchaseOrders`), so the PO vendor was always null and the
+  `syncPurchaseOrderFromNetsuite` fail-loud missing-entity guard threw every run — the actual cause of
+  the **Canon + Endeavor Health ITEM_RECEIPTS** freeze at `1-RUNNING` (watermarks ~8/~5 days). Fixed
+  additively (add `entity, BUILTIN.DF(entity) AS entity_name`; populate `$shim->entity` as
+  `{internalId,name}`); same "a field the shim consumes must be in the SELECT" class as `tl.location`.
+  Deployed ~12:52; both sections self-healed RUNNING→IDLE and resumed advancing. (jcardinal)
 - 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

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

@@ -583,8 +583,10 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
   `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`,
+  `fetchInvoiceFile` (SuiteQL `file` id lookup + **RESTlet** content fetch → `base64_decode` → raw
+  bytes; replaces `getInvoiceFile` — the `/record/v1/file/{id}` approach 404s, so a SuiteScript RESTlet
+  is the only REST path — see [File Cabinet content via RESTlet](../../library/features/netsuite-filecabinet-restlet.md)),
+  `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).
@@ -601,8 +603,105 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
   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).
 
+- **⚠ Canon + Endeavor Health ITEM_RECEIPTS froze because `fetchPurchaseOrderById` never populated the
+  PO vendor (deployed/verified 2026-08-29).** The PO shim's `->entity` was always null (its SuiteQL
+  SELECT omitted `entity`, unlike `listPurchaseOrders`), so the fail-loud missing-entity guard in
+  `syncPurchaseOrderFromNetsuite` (reached via `syncItemReceiptFromNetsuite`) threw **every** run —
+  freezing Canon (clientId 12) and Endeavor Health (clientId 11) ITEM_RECEIPTS at `1-RUNNING`,
+  watermarks frozen ~8/~5 days. Fix is in the shim
+  ([rest-shim doc](../../library/features/netsuite-suiteql-rest-shim.md)): add
+  `entity, BUILTIN.DF(entity) AS entity_name` and build `$shim->entity`. `library`-only, additive; a
+  genuinely vendorless PO still throws. Deployed ~12:52 — both sections self-healed RUNNING→IDLE and
+  resumed advancing. Same class as the missing `tl.location` SELECT.
+
+- **⚠ Diagnostic refinement — the stuck signal is specifically `1-RUNNING`, NOT any `*-RUNNING`.** A
+  section frozen because it throws every run collapses its window ÷3 all the way to **1 second**, so its
+  `NETSUITE_EXECUTION_MODE_*` reads exactly **`1-RUNNING`**. A **large-window** `<big>-RUNNING` (e.g.
+  `864000-RUNNING`) is usually just a healthy section caught **mid-execution** at the query instant —
+  not stuck. And a large-window value with a *years-old* watermark can be a legitimate long **backfill**
+  (e.g. NYCHH backfilling from 2020/2021), also not a bug. Read the window magnitude, not just the
+  RUNNING state. **Sweep method:** read every client's `Client_<X>.Parameters` for
+  `NETSUITE_EXECUTION_MODE_*` / `NETSUITE_LAST_SYNC_DATETIME_*`; a cross-schema `UNION` over many client
+  DBs needs `CONVERT(<col> USING utf8mb4)` on the value column or MySQL raises *"Illegal mix of
+  collations."* Then map each stuck client/section to an exact crash **file:line** via prod
+  `Logs.Event` — note **`Logs.Issue` has no `clientId` column but `Logs.Event` does**, so filter
+  `Logs.Event` by `clientId`.
+
+- **OPEN, NOT FIXED (observed 2026-08-29, low priority — separate tickets):**
+  - **AIG (clientId 32, held account)** crashes in the **LOOKUPS** phase at
+    `common_sync_togasupply.php:463` with `Undefined property: stdClass::$companyName` — a
+    customer-shim shape gap that **survived** the earlier `fetchCustomerById` `addressbookList` fix.
+    (AIG remains a held/non-supply account — see the AIG gotcha above.)
+  - **Adyen (clientId 48)** crashes at `common_sync_togasupply.php:99` *"Invalid API Response"* from
+    `App_Api_Toga2::send()` at **setup** — it is **stuck-IDLE** (crashes before any section writes
+    RUNNING, so the `1-RUNNING` sweep misses it — same class as a LOOKUPS/setup abort). Likely an
+    **improperly onboarded** client (cf. AIG "listed ≠ functioning"). No knowledge-base client profile
+    exists for Adyen; no supply work has been done for it — confirm it's a real supply client before
+    onboarding effort.
+  Both are pre-existing and unrelated to this session's fixes.
+
+- **⚠ A serialized unit's OWN location can differ from its receipt line's — auto-create it before the
+  `/units` write or api2 400s EV-12 (fixed 2026-08-29, `library/app/api/toga2.php`
+  `syncItemReceiptFromNetsuite`).** The unit carries its own `custitemnumber_location` (referenced on the
+  `/units` write by `c_netsuiteInternalLocationId`); when that location differs from the receipt line's
+  and isn't provisioned in the client DB, api2 rejects the unit write **EV-12**. The fix now **POSTs
+  `/locations` for the unit's own location before the write**, mirroring the existing item-line location
+  create one level up. Shared/general fix (any client running serialized item receipts), surfaced by
+  **GroWrk** location **1569**. Deployed.
+
+- **⚠ The exact api2 rejection detail lives in `Logs_<Client>.Api`, not `Logs.Event` (which TRUNCATES
+  it).** When a section throws on an api2 non-success, `Logs.Event` records the error envelope but
+  **truncates** the useful detail (the `EV-9`/`EV-12` field/`searchCriteria` specifics). The full
+  request/response is in the **per-client** `Logs_<Client>.Api` table — **join on the `transactionId`
+  carried in the error envelope**; it has `method`, `route`, `responseCode`, `requestPayload`, and
+  `responsePayload`. So the diagnosis chain is: `Client_<X>.Parameters` (localize the stuck section) →
+  `Logs.Event` filtered by `clientId` (crash file:line + `transactionId`) → `Logs_<Client>.Api` on that
+  `transactionId` (the untruncated api2 rejection). (Distinct from the fatal-before-logging case where the
+  api2 request dies before the middleware and writes **no** `Logs_<Client>.Api` row — then read
+  `Logs.Issue` instead; see the 2026-08-18 poison-order diagnostic trap above.)
+
+- **⚠ The shared `syncTransferOrderFromNetsuite` item-sync is NON-IDEMPOTENT — it creates DUPLICATE
+  `TransferOrderItems` every run (found 2026-08-29, NOT fixed; affects stocking-SO TOs too).** The shared
+  item loop does not reconcile against existing rows, so every sync appends the TO's items again: an
+  attempted real-TrnfrOrd import reached **22 duplicate items all `lineNumber` 1** on TO #15, and a
+  **pre-existing stocking-SO** transfer order (`Client_Nychh.TransferOrders` id **1** / number **62541**)
+  already carries **13 duplicates** — proving the bug is in the **shared** loop, not the real-TO path.
+  Because of this (plus an api2 `transferOrderItem`-reference gap and a receipt-line↔TO-line mapping
+  mismatch), the **real NetSuite Transfer Order (TrnfrOrd) item-receipt feature is INTENTIONALLY SKIPPED**
+  — a documented skip in `common_sync_togasupply.php`, exactly like the existing Return-Authorization
+  (`RtnAuth`) receipt skip — pending a proper rebuild. Full state, the inactive scaffolding left staged,
+  and the rebuild spec are on the
+  [NYCHH NetSuite → TransferOrders import](../../../clients/nychh/features/netsuite-transfer-order-import.md)
+  doc. **Do not re-enable real-TO receipts until the shared item loop is made idempotent (which also
+  fixes the stocking-SO dups and cleans the pre-existing TO 1).**
+
 ## Change history
 
+- 2026-08-29 — **Stabilize session, additional durable findings.** (a) `syncItemReceiptFromNetsuite`
+  now **auto-creates a serialized unit's OWN location** (`custitemnumber_location` → POST `/locations`)
+  before the `/units` write, mirroring the item-line location create — a general fix surfaced by GroWrk
+  location 1569 (unit location ≠ receipt-line location → EV-12). (b) Recorded the diagnostic that
+  `Logs.Event` **truncates** the api2 rejection detail — the untruncated `method`/`route`/`responseCode`/
+  `requestPayload`/`responsePayload` is in the per-client `Logs_<Client>.Api` table, joined on the
+  envelope's `transactionId`. (c) Recorded that the shared `syncTransferOrderFromNetsuite` item-sync is
+  **non-idempotent** (duplicate `TransferOrderItems` every run — TO #15 reached 22 dups, pre-existing
+  stocking-SO TO 1/62541 has 13), so it affects stocking-SO TOs too; the **real-TrnfrOrd item-receipt
+  feature was intentionally SKIPPED** in `common_sync_togasupply.php` (like the RtnAuth skip) pending a
+  rebuild — rebuild spec on the NYCHH TransferOrders-import doc. (jcardinal)
+- 2026-08-29 — **Deploy/verify/stabilize session for the SOAP→REST conversion.** Root-caused the
+  **Canon + Endeavor Health ITEM_RECEIPTS** freeze: `fetchPurchaseOrderById` never populated the PO
+  vendor (`entity` missing from its SuiteQL SELECT), so `syncPurchaseOrderFromNetsuite`'s fail-loud
+  missing-entity guard threw every run — fixed in the shim (add `entity`/`BUILTIN.DF(entity)`, build
+  `$shim->entity`); deployed ~12:52, both sections self-healed. Migrated **invoice-PDF retrieval to a
+  RESTlet** (`/record/v1/file/{id}` 404s — no token-only REST path to File Cabinet binary exists), which
+  unblocked Endeavor's whole pipeline; new [File Cabinet content via
+  RESTlet](../../library/features/netsuite-filecabinet-restlet.md) doc. Recorded the **`1-RUNNING`
+  (window collapsed to 1s) = stuck** vs large-window `*-RUNNING` (healthy/mid-run or legit backfill)
+  diagnostic, the cross-schema `Parameters` sweep needing `CONVERT(... USING utf8mb4)`, and that
+  `Logs.Event` (not `Logs.Issue`) carries `clientId`. Logged two OPEN, unfixed items: **AIG** (clientId
+  32) LOOKUPS crash at `:463` (`Undefined property $companyName`, customer-shim gap that survived the
+  addressbook fix) and **Adyen** (clientId 48) setup crash at `:99` (stuck-IDLE, likely improperly
+  onboarded). (jcardinal)
 - 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 →

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, 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 |
+| [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, dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql, dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.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

@@ -19,6 +19,8 @@ files:
   - 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
+  - dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql
+  - dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.sql
 ---
 
 ## Summary
@@ -490,6 +492,15 @@ hardcoded `Core.RecordFields` id literals instead of a subselect.
       and every repo is on the **same branch** so the generated model matches the DB.
 
 ## Change history
+- **2026-08-29** — Two more worked examples of the **standard-field write grant via hardcoded
+  `Core.RecordFields` id literal** (the cross-cluster caveat — a `Client_*`→`Core` JOIN is refused on the
+  prod client cluster), each cloning a working sibling: `ItemReceipts.transferOrderId` (Core RF **2153**,
+  clone `purchaseOrderId` **85**) and `ItemReceiptItems.transferOrderItemId` (Core RF **2152**, clone
+  `purchaseOrderItemId` **471**). Correct + deployed but **dormant** — they only take effect once NYCHH's
+  real-`TrnfrOrd` item-receipt path is re-enabled (deferred; see
+  [NYCHH TransferOrders import](../../../clients/nychh/features/netsuite-transfer-order-import.md)). Note
+  for the team: this recipe was in this doc all along, yet the field-ACL model was reverse-engineered from
+  DB/code first this session before the doc was consulted — search the KB first. (jcardinal)
 - **2026-08-28** — Scoped the **third gate**: `Core.AclActions` + `AclActionPermissions` is
   `_Model_Core_Page::meta()` behavior only, and is **dead config in the surface-driven `toga25-supply`
   app** — `_Model_Core_Surface::resolve()` drops an element only when the element itself declares an

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)_ — 21 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 22 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/nychh/INDEX.md

@@ -3,7 +3,7 @@
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
 | [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 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, dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql, dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.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-transfer-order-import.md

@@ -18,6 +18,8 @@ files:
   - dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql
   - dbchanges2/Client/2026-08-28a - TransferOrderItemsTimestampColumns.sql
   - dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestampColumnsReposition.sql
+  - dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql
+  - dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.sql
 related:
   - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
   - ../../../1.0/apps/library/features/toga2-api-client-and-bridge.md
@@ -160,8 +162,68 @@ that rethrows warnings as a catchable `ErrorException` with exact `file:line`. T
 `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.**
 
+## Real NetSuite Transfer Order (TrnfrOrd) item receipts — DEFERRED / SKIPPED (2026-08-29)
+
+Everything above concerns transfer orders that arrive **as NetSuite sales orders** (the stocking-flag
+routing). A *separate* case is a NetSuite item receipt whose **`createdFrom` is a real
+`TrnfrOrd` record** ("Transfer Order #N"), not a stocking sales order presenting as `'Sales Order'`.
+Importing that path was **attempted this session and INTENTIONALLY DISABLED** — a documented skip in
+`common_sync_togasupply.php`, exactly like the existing Return-Authorization (`RtnAuth`) receipt skip —
+because the feature is **not production-ready**. Do not re-enable it without doing the rebuild below.
+
+**Why it was disabled (three blockers):**
+
+1. **The shared `syncTransferOrderFromNetsuite` item-sync is NON-IDEMPOTENT.** It appends the TO's items
+   every run instead of reconciling — the attempted TO #15 reached **22 duplicate items all `lineNumber`
+   1**, and a **pre-existing stocking-SO** transfer order (`Client_Nychh.TransferOrders` id **1** /
+   number **62541**) already carries **13 duplicates**. So the duplicate bug is in the **shared** item
+   loop and affects **stocking-SO TOs too**, not just the real-TO path (see the shared
+   [per-client-sync doc](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md)).
+2. **api2 cannot resolve the receipt's `transferOrderItem` reference — `EV-12` "no searchable
+   identifiers."** `TransferOrderItems` is **not** set up to be referenced by `(transferOrder,
+   lineNumber)` the way `PurchaseOrderItems` is (which is how a receipt line normally links to its
+   order line). This needs api2 **reference metadata** making a `TransferOrderItems` identifier
+   searchable.
+3. **Receipt-line ↔ TO-line mapping is wrong.** The receipt line's `orderLine` did not match the TO
+   item's `lineNumber`, so even past the EV-12 the line link would be incorrect.
+
+**Cleanup done:** deleted the TO #15 duplicate artifact (`TransferOrder` 114 + its items).
+
+**Inactive scaffolding left STAGED for the rebuild (present but not wired live):**
+
+- `App_Api_Netsuite_Rest::fetchTransferOrderById` — real `TrnfrOrd` shim (`source` = location,
+  `dest` = `transferLocation`, `ordPicked`/`ordReceived` flags).
+- `syncTransferOrderFromNetsuite($isRealTransferOrderRecord = true)` — dest resolved from the
+  `transferLocation` warehouse; stage derived from the picked/received flags.
+- a location → client lookup in the cron.
+- the guarded `transferOrderItem` link in the receipt-item builder.
+
+**ACL grants written + deployed this session (correct, but DORMANT until real-TO receipts are
+re-enabled):** two standard-field write grants cloning a working sibling per the
+[ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md) recipe, using
+**hardcoded `Core.RecordFields` id literals** (the cross-cluster caveat — a `Client_*`→`Core` JOIN is
+refused on the prod client cluster):
+
+- `dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql` —
+  `ItemReceipts.transferOrderId` (Core RecordField **2153**), cloning `purchaseOrderId` (**85**).
+- `dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.sql` —
+  `ItemReceiptItems.transferOrderItemId` (Core RecordField **2152**), cloning `purchaseOrderItemId`
+  (**471**).
+
+**REBUILD SPEC (all four, in order, before re-enabling + removing the skip):**
+1. Make the shared `syncTransferOrderFromNetsuite` item-sync **idempotent** (reconcile against existing
+   `TransferOrderItems` by a stable key) — this also fixes the stocking-SO dups and must **clean the
+   pre-existing TO 1** (13 dups).
+2. Add api2 **`TransferOrderItems` reference metadata** so a receipt line can resolve its TO item by a
+   searchable identifier (the analogue of the `PurchaseOrderItems` `(purchaseOrder, lineNumber)` setup).
+3. **Verify the receipt-line ↔ TO-line mapping** (the `orderLine` ↔ TO-item `lineNumber` correspondence).
+4. Re-enable the path, confirm the (now non-dormant) ACL grants take effect, and **remove the skip**.
+
 ## Gotchas / known issues
 
+- **Real-TrnfrOrd item receipts are disabled — see the DEFERRED section above.** A receipt whose
+  `createdFrom` is a real Transfer Order is skipped by design; do not read that as the importer being
+  broken.
 - **Order 128829 (no location anywhere) is unresolved** — see the origin-resolution section. Do not
   assume the importer is broken if this single order is stuck; every located order imports.
 - **Routing is gated by the wrapper constant.** If a future client should route transfer orders,
@@ -174,6 +236,18 @@ that rethrows warnings as a catchable `ErrorException` with exact `file:line`. T
 
 ## Change history
 
+- 2026-08-29 — Recorded the **real NetSuite `TrnfrOrd` item-receipt feature as DEFERRED/SKIPPED**
+  (documented skip in `common_sync_togasupply.php`, like the `RtnAuth` skip) after attempting it and
+  hitting three blockers: the shared `syncTransferOrderFromNetsuite` item-sync is **non-idempotent**
+  (TO #15 got 22 dup items; pre-existing stocking-SO TO 1/62541 has 13 — shared-loop bug, affects
+  stocking-SO TOs too), api2 can't resolve the receipt's `transferOrderItem` reference (`EV-12`, no
+  searchable identifier on `TransferOrderItems`), and the receipt-line `orderLine` ≠ TO-item `lineNumber`.
+  Deleted the TO #15 dup artifact (TransferOrder 114). Left inactive scaffolding staged
+  (`fetchTransferOrderById`, `syncTransferOrderFromNetsuite($isRealTransferOrderRecord=true)`,
+  location→client lookup, guarded `transferOrderItem` link). Wrote + deployed (but **dormant**) two ACL
+  field-permission grants using hardcoded Core RecordFields literals: `ItemReceipts.transferOrderId`
+  (RF 2153, clone `purchaseOrderId` 85) and `ItemReceiptItems.transferOrderItemId` (RF 2152, clone
+  `purchaseOrderItemId` 471). Documented the four-step rebuild spec. (jcardinal)
 - 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`

package/knowledge/standalone/standards/session-priming.md

@@ -40,6 +40,12 @@ This is a team directive. It applies to every session, both frameworks, every re
    write, or spawn agents.
 5. **Ordering is unchanged.** The team KB stays the **first** source, ahead of all other
    research — that part was already correct and stays.
+6. **Search the KB before reverse-engineering — mid-session, not just at kickoff.** Before
+   reverse-engineering any code, schema, or framework mechanism from the source or the live DB,
+   FIRST search the team KB (`node "<TEAM_REPO>/knowledge.js" search --q=…`). The KB is large and
+   usually already documents the mechanism — reaching for DB/code archaeology first is the mistake.
+   This extends rule 5 (KB is the first source) from kickoff to every point in a session where you
+   are about to derive how something works.
 
 ## How it is enforced
 
@@ -68,6 +74,12 @@ than the old subagent approach did. Mitigate by not re-reading absorbed docs and
 only the needed section of a large spec — but priming in the main session is the requirement.
 
 ## Change history
+- 2026-08-29 — Added rule 6: search the KB before reverse-engineering any code/schema/framework
+  mechanism, mid-session and not only at kickoff. Prompted by a NetSuite→TOGa Supply session that
+  reverse-engineered the entire 2.0 field-ACL model (AclFieldPermissions, Core.RecordFields,
+  EV-9/EV-12, the add-a-writable-field recipe, the cross-cluster hardcoded-literal caveat) from
+  DB/code before discovering it was fully documented in
+  `2.0/apps/_underscore/features/acl-permission-chain.md` all along. (jcardinal)
 - 2026-08-13 — Standard recorded. Kickoff priming must run in the main session, synchronously,
   and no subagent may start until priming is complete; released by the new
   `knowledge.js kickoff-primed` sentinel. Retired the `context-primer` subagent from the

package/package.json

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