toga-ai 1.0.548 → 1.0.549

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

@@ -14,7 +14,7 @@
 | [Running 2.0 code from a bare CLI script (bootstrap + transactions)](features/cli-script-bootstrap.md) | A throwaway CLI script (a data check, a backfill dry-run, a render harness) that wants the real 2.0 framework — `_Model`, `_Query`, `_Database` — is **not** the | _underscore/Database.php, _underscore/Environment.php, api2/Initialize.php |
 | [_Cloud S3 helpers (copy / get / delete / list)](features/cloud-s3-helpers.md) | `_Cloud` centralizes AWS SDK S3 usage for the 2.0 stack so the `S3Client` never leaks into workers or app code. | _underscore/Cloud.php |
 | [_Component_*/_Model_* project-namespace registration (autoloader) & backslash-qualify traps](features/component-model-namespace-registration.md) | Every **project-local** `_Component_*` and `_Model_*` class in a 2.0 app **must declare the project namespace** at the top of the file: ```php namespace <NAMESP | _underscore/Loader.php, worker2/_.php, api2/_.php, worker2/Component/Forecast/Db/Db.php, worker2/Component/Forecast/SaleImport/SaleImport.php, worker2/Component/Api/Oneuptime/Oneuptime.php, api2/Component/Api/Netsuite/Netsuite.php, _underscore/Component/Api/Paypal/Paypal.php |
-| [_Config group access — the two-argument "optional" form does NOT rescue a missing GROUP](features/config-group-access.md) | `_Config::<group>('<property>')` reads a value out of the active `Config/<ENVIRONMENT>.ini`, and **it throws when the requested group is absent from the ini.** | _underscore/Config.php, _underscore/Component/Api/Paypal/Paypal.php |
+| [_Config group access — the two-argument "optional" form does NOT rescue a missing GROUP](features/config-group-access.md) | `_Config::<group>('<property>')` reads a value out of the active `Config/<ENVIRONMENT>.ini`, and **it throws when the requested group is absent from the ini.** | _underscore/Config.php, _underscore/Component/Api/Paypal/Paypal.php, _underscore/Worker.php, api2/Config/beta.ini, api2/Config/sandbox-dev.ini |
 | [Re-pointing a DB alias mid-request (_Database::register park/restore)](features/database-alias-repointing.md) | `_Database` keys **all live per-database runtime state by the connection ALIAS** (`Client` / `_underscore::DB_CLIENT`, `ClientLogs`, `Archive`), **not** by the | _underscore/Database.php, _underscore/Query.php, api2/Component/Api/V2/V2.php, api2/Component/Api/CrossClient/CrossClient.php |
 | [2.0 Email Send Pipeline (queue + Send worker)](features/email-send-pipeline.md) | In 2.0, `_Email::send()` **does not transmit** — it queues the message. | _underscore/Email.php, _underscore/String.php, worker2/Worker/Infrastructure/Email/Send.php |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
@@ -23,7 +23,7 @@
 | [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | worker2/Component/Forecast/SaleImport/SaleImport.php, worker2/Component/Forecast/Db/Db.php, _underscore/Component/Api/Netsuite/Netsuite.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/JournalEntry.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Forecast/2026-06-26a - Add journalEntry to Sales transaction type enum.sql, test/@dave/test_invoice_lifecycle.php, test/@dave/test_je_lifecycle.php, test/@dave/test_creditmemo_lifecycle.php, test/@dave/test_cashsale_lifecycle.php, test/@dave/test_cashrefund_lifecycle.php, test/@dave/test_fetchrecord_routes.php, test/@dave/verify_je_classification.php, test/@dave/probe_je_accounts.php, test/@dave/probe_je_shape.php, test/@dave/fixer.php, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/Junk Drawer/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
 | [isFulfillable Propagation Up the SO↔PO Chain](features/fulfillable-item-propagation.md) | `Items.isFulfillable` is a boolean that gates whether a storefront line's **Qty Fulfilled** cell is actionable. | _underscore/Model/Client/Item.php, _underscore/Model/Compass/Item.php, dbchanges2/Core/2026-07-17 - Items isFulfillable RecordField.sql, dbchanges2/Core/2026-07-17 - RegisterItemIsFulfillableInterceptors.sql, dbchanges2/Client/2026-07-17 - ItemsisFulfillable.sql |
 | [Item-Fulfillment Stage Lifecycle (picked/packed/shipped) & Order Status](features/item-fulfillment-stage-lifecycle-and-order-status.md) | Every ItemFulfillment (IF) now carries an explicit **stage** — picked → packed → shipped — resolved through `ItemFulfillmentStages → ItemFulfillmentStatuses` (m | _underscore/Model/Client/SalesOrder.php, _underscore/Model/Quad/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/SalesOrderStatus.php, _underscore/Model/Client/SalesOrderItem.php, _underscore/Model/Client/Item.php, _underscore/Model/Client/PurchaseOrderItem.php, library/app/api/toga2.php, dbchanges2/Client/2026-06-30a - BackfillNullStageItemFulfillmentsToShipped.sql, dbchanges2/Client/2026-06-30b - SalesOrderStatusesPickedPacked.sql, dbchanges2/Client/2026-06-30c - ItemFulfillmentStageIdNotNull.sql, dbchanges2/Client_CompassCanada/2026-06-30a - ItemFulfillmentLifecycleAndShippedBackfill.sql |
-| [DB-free unit testing for _underscore model interceptors](features/model-interceptor-unit-testing.md) | `_underscore` shipped with **no** PHPUnit setup (no `composer.json`/`phpunit`; only vendored PhpOffice tests existed). | _underscore/Test/bootstrap.php, _underscore/Test/Prudential/ServiceRequestTest.php |
+| [DB-free unit testing for _underscore model interceptors](features/model-interceptor-unit-testing.md) | `_underscore` shipped with **no** PHPUnit setup (no `composer.json`/`phpunit`; only vendored PhpOffice tests existed). | _underscore/Test/bootstrap.php, _underscore/Test/Prudential/ServiceRequestTest.php, test/@Bala/tests/netsuite_salesorder_payload_tests.php |
 | [_Model magic-field access (__get without __isset)](features/model-magic-field-access.md) | `_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`. | _underscore/Model/Core/Model.php, _underscore/Model.php, _underscore/Model/Rate/Subscription.php |
 | [_Model::save() vs raw _Query — no atomic conditional update](features/model-save-vs-query-atomic-update.md) | `_Model::save()` is a plain load-then-write ORM primitive and **cannot express an atomic conditional update** (an optimistic-concurrency / row-claim guard such | _underscore/Model.php, _underscore/Query.php, _underscore/Model/Rate/Subscription.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php |

package/knowledge/2.0/apps/_underscore/features/config-group-access.md

@@ -6,11 +6,14 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-06
-owners: ["mhammontree"]
+updated: 2026-08-10
+owners: ["mhammontree", "bala"]
 files:
   - _underscore/Config.php
   - _underscore/Component/Api/Paypal/Paypal.php
+  - _underscore/Worker.php
+  - api2/Config/beta.ini
+  - api2/Config/sandbox-dev.ini
 related:
   - ./cli-script-bootstrap.md
   - ./model-magic-field-access.md
@@ -72,6 +75,23 @@ environment without a `[paypal]` section returned **`EO-1` with a stack trace to
 retail customer** instead of failing cleanly with a business message. Guarding with
 `isGroupSet()` turned it into a controlled `_Exception_Business`.
 
+## A missing **key inside a group that exists** throws too — and framework internals read keys you didn't
+
+The table above is easy to read as "worry about missing groups." The single-argument form
+**throws on a missing property as well** (`Config.php:79`), and the keys at risk are often ones
+**your code never mentions** because a framework helper reads them.
+
+Concrete case (2026-08-10, Elite sales-order push): `_Worker::runTask`'s non-debug path reads
+`[cloud] aws_worker_queue_url` and `aws_worker_queue_region`. `api2/Config/beta.ini` and
+`sandbox-dev.ini` both **had a `[cloud]` group but neither key**; `production.ini` had both. A
+`postPost` interceptor calling `runTask` therefore produced an **uncaught throw → HTTP 500 `EO-1`
+with a null envelope and no log row** — a failure that looks nothing like "config". Fixed by adding
+the two keys to `beta.ini` and `sandbox-dev.ini`.
+
+**Rule:** when you introduce a call into a framework helper (`_Worker::runTask`, a carrier client, an
+S3 helper) from a new tier, **diff that tier's ini against `production.ini` for the keys the helper
+reads** — the group existing proves nothing.
+
 ## Gotchas / known issues
 
 - **`_Config::<group>('prop', false)` is NOT a null-safe read.** It is property-optional only.
@@ -86,6 +106,13 @@ retail customer** instead of failing cleanly with a business message. Guarding w
 
 ## Change history
 
+- 2026-08-10 — Recorded that a **missing key inside an existing group throws as well**
+  (`Config.php:79`), and that the risky keys are the ones **framework helpers** read on your behalf:
+  `_Worker::runTask`'s non-debug path needs `[cloud] aws_worker_queue_url` /
+  `aws_worker_queue_region`, which `api2/Config/beta.ini` and `sandbox-dev.ini` lacked (both had a
+  `[cloud]` group; `production.ini` had the keys) — so an interceptor calling `runTask` returned
+  **`EO-1` with a null envelope and no log row**. Keys added to both files; the durable rule is to
+  diff a tier's ini against `production.ini` for the keys a newly-called helper reads. (bala)
 - 2026-08-06 — TRUE-80282 testing: documented that `_Config::<group>()` **throws when the group is
   absent** and that the two-argument "optional" form does **not** rescue a missing group —
   `_Config::__callStatic` (`Config.php:64-87`) tests `$properties[0]` for the optional flag

package/knowledge/2.0/apps/_underscore/features/model-interceptor-unit-testing.md

@@ -6,13 +6,15 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-24
+updated: 2026-08-10
 owners: ["bala"]
 files:
   - _underscore/Test/bootstrap.php
   - _underscore/Test/Prudential/ServiceRequestTest.php
+  - test/@Bala/tests/netsuite_salesorder_payload_tests.php
 related:
   - ../../../../clients/prudential/features/service-request-address-validation.md
+  - ../../worker2/features/netsuite-salesorder-outbound-push.md
 ---
 
 ## Summary
@@ -56,11 +58,22 @@ Verified 6/6 passing against the real code.
   making them public just to test them.
 - **Stub only the persistence base, load the real logic.** The value of the pattern is that the
   production validator runs unchanged; do not reimplement the validator in the stub.
+- **The pattern travels beyond `_underscore` models.** The same stub-the-dependencies +
+  reflect-into-privates technique was applied to a **worker2 action** from the `test` repo
+  (`test/@Bala/tests/netsuite_salesorder_payload_tests.php`, 76 tests, plain PHP rather than
+  PHPUnit): it `require`s the real `worker2/Worker/Netsuite/SalesOrder.php` with stubbed framework
+  dependencies and drives its private builders/resolvers by reflection. Use it as the second worked
+  example — see
+  [Toga → NetSuite sales-order push](../../worker2/features/netsuite-salesorder-outbound-push.md).
 - There is still no `composer.json`/autoloader for the repo — tests rely on the explicit
   `--bootstrap` file to wire up requires. Adding more model tests means extending
   `Test/bootstrap.php` with the stubs that model needs.
 
 ## Change history
+- 2026-08-10 — Noted that the stub + reflect-into-privates pattern also carries to **worker2 actions**
+  driven from the `test` repo (`test/@Bala/tests/netsuite_salesorder_payload_tests.php`, 76 tests,
+  plain PHP, loading the real `Worker/Netsuite/SalesOrder.php`) — a second worked example of testing
+  shipped code rather than a copy. (bala)
 - 2026-07-24 — Created: first PHPUnit scaffold in `_underscore` (`Test/bootstrap.php` +
   `Test/Prudential/ServiceRequestTest.php`), a DB-free pattern that stubs the model's persistence
   base and reflects into private interceptor validators; seeded with 6 regression tests for the

package/knowledge/2.0/apps/_underscore/features/netsuite-rest-client.md

@@ -6,12 +6,13 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-05
+updated: 2026-08-10
 owners: ["dfranks", "jcardinal", "bala"]
 files:
   - _underscore/Component/Api/Netsuite/Netsuite.php
 related:
   - ../../worker2/features/netsuite-salesorder-open-orders-sync.md
+  - ../../worker2/features/netsuite-salesorder-outbound-push.md
   - ../../worker2/features/netsuite-opportunity-sync.md
   - ../architecture.md
 ---
@@ -86,17 +87,21 @@ through `_ApiRequest` directly (mirroring `send()`'s auth/endpoint/header setup)
   numeric id tolerating a query string or fragment.
 - Throws on non-2xx, on no `Location` header, and on no id parsed.
 
-> **⚠ BUG (live, not yet fixed):** the trailing-id regex was written as `'#/(\d+)(?:[?#]|$)#'`,
-> which uses `#` as the PCRE **delimiter** *and* puts `#` inside the `[?#]` character class — so PHP
-> reads the class-`#` as a premature closing delimiter and the whole pattern **always throws
-> `preg_match(): Unknown modifier ']'`**. This fires *after* the record is already created, so the
-> create succeeds in NetSuite but `createRecord()` raises and the caller never gets the new id —
-> it breaks the entire outbound create/push path **for any record type** (observed on `journalentry`
-> and again on `invoice` create). **Fix direction:** change the delimiter so `#`
-> isn't both delimiter and class member, e.g. `~/(\d+)(?:[?#]|$)~`. Interim workaround used in
-> probes and in `test/@dave/test_invoice_lifecycle.php`: parse the new internalId off the `Location`
-> value carried in the thrown exception message (the lifecycle harness ships its own correct
-> `~`-delimited parse to sidestep this without editing the framework). Confirmed live 2026-06-26.
+> **✅ FIXED 2026-08-10 (`Netsuite.php` ~L198) — re-delimited to `~`.** The trailing-id regex was
+> written as `'#/(\d+)(?:[?#]|$)#'`, which used `#` as the PCRE **delimiter** *and* put `#` inside
+> the `[?#]` character class — PHP read the class-`#` as a premature closing delimiter, treated
+> `]|$)` as modifiers, and `preg_match()` returned `false` with **`Unknown modifier ']'`**. So
+> `createRecord()` could **never** return: it broke the outbound create/push path for **every**
+> record type (observed on `journalentry`, `invoice`, and `salesOrder`). The fix is simply the `~`
+> delimiter. The old interim workaround — parsing the id out of the thrown exception message, as
+> `test/@dave/test_invoice_lifecycle.php` does — is no longer needed for new code.
+>
+> **⚠ Keep the consequence in mind, it outlives the bug:** the failure happened **after** the HTTP
+> 201 *and* after the `Location` header was read — NetSuite had already created the record. Any
+> "create succeeded but we crashed after" fault in this class therefore leaves an **orphan in
+> NetSuite with nothing in Toga pointing at it** (this bug orphaned two Elite sales orders in live
+> account 1095849). **Never blind-retry a failed `createRecord()` — look the record up in NetSuite
+> first.**
 
 ### Read — `fetchRecord(string $route, string $label): array`
 
@@ -163,12 +168,22 @@ doc.)
 - **204-with-empty-body is success, not failure.** Both create (204 + `Location`) and update (204,
   no body) return no payload; treat a 2xx with empty body as success and key off the status, not the
   body.
-- **`createRecord()`'s trailing-id regex is a live `#`-delimiter bug** (`'#/(\d+)(?:[?#]|$)#'` →
-  always `Unknown modifier ']'`), thrown *after* the record is created — see the ⚠ note under
-  *Create* for the cause and the `~…~`-delimiter fix.
+- **A `createRecord()` failure does NOT mean the record wasn't created.** The id parse happens after
+  the 201 + `Location` read, so a post-create fault leaves an **orphan in NetSuite**. Check NetSuite
+  before retrying. (The `#`-delimiter regex bug that caused this class of orphan was fixed
+  2026-08-10 — see the note under *Create*.)
 
 ## Change history
 
+- 2026-08-10 — **Fixed the `createRecord()` trailing-id regex** (`Netsuite.php` ~L198): re-delimited
+  `'#/(\d+)(?:[?#]|$)#'` → `~`, so `preg_match` no longer returns `false` with
+  *"Unknown modifier ']'"* and the method can actually return an internalId. Recorded the durable
+  consequence — the throw fired **after** the 201 and the `Location` read, so NetSuite had already
+  created the record: this bug left **two orphaned Elite sales orders in live account 1095849**, and
+  any post-create fault in this class must be diagnosed by looking the record up in NetSuite rather
+  than by retrying. Surfaced building the
+  [Toga → NetSuite sales-order push](../../worker2/features/netsuite-salesorder-outbound-push.md).
+  (bala)
 - 2026-08-05 — Recorded the **SuiteQL custom-column filter trap**: a NetSuite custom column
   (e.g. `inventorynumber.custitemnumber_asset_tag`/`_mac_address`) can be `SELECT`ed but **not**
   filtered on — `WHERE custitemnumber_asset_tag IS NOT NULL` returns 0 rows with no error. Drive

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

@@ -3,7 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [API (api2 / TOGa API v2) Architecture](architecture.md) | `api2` is the backend powering the public **TOGa 2.0 API**. | api2/Controller/Index.php, api2/Component/Api/V2/V2.php, api2/Component/Api/Cxml/Cxml.php, api2/Component/Api/V2/Response/Response.php, api2/Config/ |
-| [API Payload Interceptors (metadata-registered prePost/postPut model hooks)](features/api-payload-interceptors.md) | A `_Model`'s `prePost()` / `postPost()` / `prePut()` / `postPut()` hooks are **not** called by the model. | api2/Component/Api/V2/V2.php, _underscore/Model/Client/ItemFulfillment.php, dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql |
+| [API Payload Interceptors (metadata-registered prePost/postPut model hooks)](features/api-payload-interceptors.md) | A `_Model`'s `prePost()` / `postPost()` / `prePut()` / `postPut()` hooks are **not** called by the model. | api2/Component/Api/V2/V2.php, api2/Controller/Index.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Elite/SalesOrder.php, dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql |
 | [Multi-Client (Cross-Client) Data Retrieval](features/cross-client-data-retrieval.md) | A single authenticated V2 GET listing can return records across **many** clients (designed for 1000+) that the caller is entitled to, honoring **each target cli | api2/Component/Api/CrossClient/CrossClient.php, api2/Component/Api/V2/V2.php, api2/Controller/Index.php, _underscore/Model/Cache/Table.php, _underscore/Model/Cache/Tables/Client.php, _underscore/Model/Core/Record.php, worker2/Worker/Platform/Cache.php, worker2/Controller/Index.php, worker2/_.php, dbchanges2/Cache/2026-06-30a - MultiClientCacheTables.sql, dbchanges2/Core/2026-06-30b - CacheClusterRegistrationAndRecordTtl.sql, dbchanges2/Core/2026-07-27a - PlatformCacheCleanCron.sql |
 | [Encrypted-User-UUID Auth Handoff (/auth/encrypted-user-uuid)](features/encrypted-user-uuid-auth-handoff.md) | `POST /auth/encrypted-user-uuid` is the intended **cross-client / SSO-handoff identity mechanism**: given an encrypted `{client, user}` UUID pair, it mints a fr | api2/Component/Api/CrossClient/CrossClient.php |
 | [ENVIRONMENT (not the EB environment name) decides the _underscore branch and Config file](features/environment-variable-drives-underscore-branch.md) | An api2 Elastic Beanstalk instance decides **which `_underscore` branch it clones** and **which `Config/<env>.ini` it loads** from the EB environment property * | api2/.ebextensions/git.php, api2/.ebextensions/php_include_underscore.config, api2/.ebextensions/git.sandbox-dev.json, api2/Config/beta.ini, api2/Config/sandbox-dev.ini, api2/Component/Api/V2/V2.php |

package/knowledge/2.0/apps/api2/features/api-payload-interceptors.md

@@ -6,17 +6,22 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-04
-owners: ["mhammontree", "dfranks"]
+updated: 2026-08-10
+owners: ["mhammontree", "dfranks", "bala"]
 files:
   - api2/Component/Api/V2/V2.php
+  - api2/Controller/Index.php
   - _underscore/Model/Client/ItemFulfillment.php
+  - _underscore/Model/Elite/SalesOrder.php
   - dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql
 related:
   - ./record-scripts.md
   - ../architecture.md
   - ../../_underscore/features/acl-permission-chain.md
   - ../../_underscore/features/recursive-item-fulfillments.md
+  - ../../_underscore/features/config-group-access.md
+  - ../../worker2/features/creating-worker-actions.md
+  - ../../../clients/elite/features/salesorder-netsuite-push.md
 ---
 
 ## Summary
@@ -126,6 +131,78 @@ per-region subclass does *not* need its own copy. Do not add duplicate hooks per
   advance-shipping-notices, **179** approval-decisions) all map 1:1 to real methods — **the row whose
   record has no corresponding method is the anomaly.**
 
+## Queueing background work from a post interceptor — the rules that make it work
+
+A `postPost`/`postPut` hook that hands work to worker2 (`_Worker::runTask`) sits in the hardest spot
+in the stack: it runs **inside api2's open transaction**, its payload is shallow, and its reads
+default to a **read replica**. All five rules below were paid for in a single build (the Elite
+sales-order push, 2026-08-10) and every one of them fails **silently or only in production**.
+
+### 1. `$api->internalApiRequest()` returns records **FLAT** — there is no `data` wrapper
+
+It returns `(object) processRoutePairs(...)`, so the shape is **`$response->salesOrders`**, *not*
+`$response->data->salesOrders`. The `data` envelope exists only on a real **HTTP** response.
+In-tree proof: `_underscore/Model/Client/SalesOrder.php:373` reads
+`$templateResponse->approvalTemplates`.
+
+This cost a full debugging cycle: the wrong path returned `null` every time, so the hook logged and
+returned **without queueing** — producing a clean `201` with no worker job and no visible error.
+
+### 2. `ApiPayloadInterceptors.minDepth` does **not** deepen a POST interceptor's payload
+
+In `api2/Component/Api/V2/V2.php` the POST response is serialized by `getFullModelData` at
+**~L5407**, but the `minDepth` bump for **post** interceptors happens at **~L5892-5900** — *after*.
+So raising `minDepth` cannot give a `postPost` hook a deeper payload. **When a post interceptor
+needs depth, use `internalApiRequest`.** (Depth matters more than it looks: at depth 3 an order's
+`shipToAddress.state.country` is absent entirely — country sits four levels down.)
+
+### 3. The hook runs inside api2's transaction — another process cannot see the new row
+
+The commit is at **`api2/Controller/Index.php:427`**, gated on `$api->response->isSuccess`, **after**
+`execute()` returns. A worker that starts before that commit reads nothing: the symptom is
+*"SalesOrder id=NNN not found"* from a job that was queued correctly.
+
+### 4. …and the reader connection cannot see it **at all** — this fails 100% in prod, 0% on beta
+
+`_Database::$_isReadHostEnabled` defaults to **TRUE**, so `SELECT`s go to the reader
+(`Query.php:273`). A reader is a **different connection**, so an uncommitted row is invisible to it —
+this is **not replication lag**, and no amount of waiting fixes it. `Core.DatabaseHosts` is what
+makes the bug environment-dependent:
+
+| Environment | hostWriter | hostReader |
+|---|---|---|
+| production (env 1) | `writer.client.database.togahub.com` | `reader1/2/3.*` |
+| dev-sandbox (env 4) | *same endpoint* | *same endpoint* |
+
+So this entire class of bug is **invisible on beta/dev-sandbox and fails on every production
+request.** Never conclude "it works on beta" for an in-request read-after-write.
+
+### 5. The pattern that works
+
+- Read the record **inside the same request** with `internalApiRequest`, wrapped in
+  `getIsReadHostEnabled()` / `setIsReadHostEnabled(false)` and restored in a **`finally`** (pin the
+  read to the writer, then put the flag back for everyone else).
+- **Pass the resulting object along in the job parameters** so the worker never re-reads it. (The
+  worker action must accept it — see
+  [Toga → NetSuite sales-order push](../../worker2/features/netsuite-salesorder-outbound-push.md),
+  whose `?object $salesOrder` parameter exists for exactly this.)
+- Pass **`false`** for `internalApiRequest`'s 5th argument (`$throwExceptionsOnError`). Its throw is
+  guarded by `!empty($this->response->messages)` on the **shared** response object, and
+  `json_encode([])` is the **truthy** string `"[]"` — so it throws even with **zero real errors**
+  once any message (even a warning) is present anywhere in the request.
+
+### Two more failure modes to expect on this path
+
+- **Config drift kills it before it starts.** `_Worker::runTask`'s non-debug path reads
+  `[cloud] aws_worker_queue_url` / `aws_worker_queue_region`, and `_Config::__callStatic` **throws on
+  a missing key even inside a group that exists** — an uncaught throw from `postPost` surfaces as
+  **HTTP 500 `EO-1` with a null envelope and no log row**. See
+  [_Config group access](../../_underscore/features/config-group-access.md).
+- **`debug_mode` changes how `runTask` dispatches**, and the debug path runs the worker *inside* your
+  open transaction — so it always fails a read-back. Also, an **absent `WorkerJobs` row is
+  ambiguous** ("never queued" vs "queued, never consumed"). Both are covered in
+  [Creating Worker Actions](../../worker2/features/creating-worker-actions.md).
+
 ## Worked example — the EV-10 that was not a code bug
 
 `_Model_Client_ItemFulfillment::prePost()` defaults `itemFulfillmentStageId` to the shipped stage on
@@ -158,6 +235,15 @@ and the failing environment**. It is a small table, and the drift is usually exa
   metadata — "works in prod, not in beta/dev-sandbox" is the signature of drift, not of a bad
   deploy. See the
   [non-prod metadata drift repair workflow](../../dbchanges2/workflows/nonprod-metadata-drift-repair.md).
+- **⚠ An in-request read-after-write in an interceptor works on beta and fails 100% in production.**
+  Reads default to the **reader** connection, which cannot see the request's own uncommitted row;
+  dev-sandbox points writer and reader at the same endpoint, so it hides the bug. Pin with
+  `setIsReadHostEnabled(false)` (restore in `finally`).
+- **`internalApiRequest` has no `data` envelope** (`$response->salesOrders`, not
+  `$response->data->salesOrders`), and `minDepth` cannot deepen a POST interceptor's payload — the
+  bump happens after serialization. A wrong read path here is a **silent no-queue with a clean 201**.
+- **Anything a post interceptor queues must survive the transaction boundary** — pass the record
+  snapshot in the job parameters rather than letting the worker re-read it.
 - **Never emit output from an interceptor.** A stray `echo`/`print_r` corrupts the `/v2`
   `{isSuccess,…,data}` envelope (this really happened in `ItemFulfillment.php` — see the
   carrier-shipping-labels doc).
@@ -166,6 +252,22 @@ and the failing environment**. It is a small table, and the drift is usually exa
 
 ## Change history
 
+- 2026-08-10 — Added **Queueing background work from a post interceptor**, five verified rules from
+  the Elite sales-order push: (1) `internalApiRequest` returns records **flat** —
+  `$response->salesOrders`, not `$response->data->salesOrders` (the `data` envelope exists only on a
+  real HTTP response; in-tree proof `_underscore/Model/Client/SalesOrder.php:373`) — and getting it
+  wrong yields a clean 201 with no job and no error; (2) `minDepth` **cannot** deepen a POST
+  interceptor's payload (serialization at `V2.php` ~L5407 precedes the post-interceptor bump at
+  ~L5892-5900); (3) hooks run inside api2's transaction, committed at `Controller/Index.php:427`
+  after `execute()`, so another process sees *"id not found"*; (4) reads default to the **reader**
+  connection (`_Database::$_isReadHostEnabled`, `Query.php:273`), which cannot see the uncommitted
+  row **at all** — and because dev-sandbox's `Core.DatabaseHosts` points writer and reader at one
+  endpoint while production splits them, the bug is **invisible on beta and fails 100% in prod**;
+  (5) the working pattern — writer-pinned `internalApiRequest` (`setIsReadHostEnabled(false)`,
+  restored in `finally`), snapshot passed in the job parameters, and `$throwExceptionsOnError =
+  false` because the throw is guarded on the shared `response->messages` where `json_encode([])` is
+  the truthy `"[]"`. Cross-linked the `[cloud] aws_worker_queue_*` config-drift `EO-1` and the
+  `debug_mode`/absent-`WorkerJobs`-row traps. (bala)
 - 2026-08-04 — Documented the **inverse failure mode**: the derived-name dispatch is **unguarded at
   all four `V2.php` call sites** (`~L8655` lookup, `~L3148` pre, `~L5694` post, `~L7411`/`~L7437`
   alternate pre) and there is **no `phpMethod` column in production**, so one row naming a

package/knowledge/2.0/apps/api2/workflows/codepipeline-codeconnections-deploy.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: workflow
 status: active
-updated: 2026-07-31
-owners: ["jcardinal", "mhammontree"]
+updated: 2026-08-10
+owners: ["jcardinal", "mhammontree", "bala"]
 files:
   - api2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh
   - api2/ebs/register_instance_to_shared_application_load_balancer.php
@@ -142,6 +142,42 @@ Production is deliberately skipped and still registers by the existing process.
 which is also the reference implementation — **api2's copy has known security defects**, including
 a committed IAM access key.
 
+### Gotcha: staleness is **per-INSTANCE**, not per-branch — verify the box that CONSUMES THE QUEUE
+
+Two `worker2` instances can serve the **same Core database while running different code**, and the
+one you test through is not the one that runs your queued jobs. Seen 2026-08-10 on the Elite
+sales-order push:
+
+| Instance | Role | Result |
+|---|---|---|
+| `i-0262cfdc6cb97a3d2` | web tier behind `worker.beta.togahub.com` | current code + NetSuite credentials → **succeeded** |
+| `i-0be8ef2e550dec05b` | **SQS consumer** (env `e-rimmbihkge`, `WorkerSandboxDevQueue`) | rejected the identical parameter with *"Unknown named parameter `$salesOrderUuid`"* and separately failed NetSuite auth |
+
+The EB bundle logs proved the consumer's last `app_source_bundle` extraction was **7 days earlier**.
+Note how the symptom lies: *"Unknown named parameter"* reads like a caller/contract bug, and an auth
+failure reads like a credentials problem — both were just **old code on one box**.
+
+**Procedure:** take the failing job's **`Core.WorkerJobs.instanceId`**, and verify *that* instance
+(and the EB environment that consumes the queue) actually received the deploy. "I deployed beta" is
+not a verification — a direct POST to the worker URL only proves the **web** instance.
+
+### Where each tier's `error_log()` output actually goes
+
+`worker2` ships `/var/log/php-fpm/www-error.log` to the CloudWatch log group **`worker`** via
+`.platform/hooks/postdeploy/020-cloudwatch-www-error.sh`. **`api2` has no equivalent hook** — so
+api2 `error_log()` output (including an interceptor's silent-skip messages) is **not in CloudWatch**
+and must be pulled from the EB request/full logs. Do not conclude "the code never logged" from an
+empty CloudWatch search on the api2 tier.
+
+### Credentials live in the committed `Config/*.ini` files (finding, 2026-08-10)
+
+Both `worker2` and `api2` carry **live secrets in `Config/*.ini` files that are committed to those
+repos** — NetSuite OAuth `clientId`/`certificateId`, AWS keys, database passwords, a Talos agent key.
+Document only **where** they live, never the values. **Recommendation (not actioned):** move them to
+**EB environment properties or SSM Parameter Store** and treat anything currently committed as
+rotate-on-exposure. Related: api2's ALB auto-registration copy also carries a committed IAM access
+key (see the auto-registration note above).
+
 ### On-instance composer install (when a dep is missing post-deploy)
 If a Composer dep is missing on the running instance (e.g. `Class "FPDF" not found` because
 `composer.lock` wasn't committed), you can install it on the box over SSH/PuTTY — but
@@ -164,6 +200,17 @@ aws codeconnections get-connection --connection-arn "<CONN_ARN>" --region "$REGI
 ```
 
 ## Change history
+- 2026-08-10 — Added three deploy-verification facts from the Elite sales-order push: (1) **staleness
+  is per-INSTANCE** — the worker2 web instance behind `worker.beta.togahub.com`
+  (`i-0262cfdc6cb97a3d2`) ran current code while the **SQS consumer** (`i-0be8ef2e550dec05b`, env
+  `e-rimmbihkge`, `WorkerSandboxDevQueue`) was 7 days stale and failed the same job with *"Unknown
+  named parameter"* + a NetSuite auth error, so verify by `Core.WorkerJobs.instanceId` and by the
+  environment that **consumes the queue**, not by "I deployed beta"; (2) worker2 ships
+  `www-error.log` to the CloudWatch group `worker` via
+  `.platform/hooks/postdeploy/020-cloudwatch-www-error.sh` but **api2 has no such hook**, so api2
+  `error_log()` output is only in the EB request/full logs; (3) recorded that live credentials sit in
+  the **committed** `worker2`/`api2` `Config/*.ini` files (locations only — no values) with the
+  recommendation to move them to EB environment properties / SSM. (bala)
 - 2026-07-31 — TRUE-80487: added the **full cross-tier "beta" environment map** after it cost two
   wasted deploys. `api.beta.togahub.com` is EB env **`API-Sandbox-Dev`** on the **`dev-sandbox`**
   database, cloning `_underscore` **`_sandbox-dev`**; `toga2-view`'s Amplify target **named

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

@@ -26,6 +26,7 @@
 | [NetSuite Integrations Monitor (Monitor/Operations/NetsuiteIntegrations)](features/netsuite-integrations-monitor.md) | `_Worker_Monitor_Operations::NetsuiteIntegrations()` is a cross-client health check that detects **stuck NetSuite ↔ 2.0 integrations**. | worker2/Worker/Monitor/Operations.php, dbchanges2/Core/2026-08-10a - Netsuite Integrations Monitor.sql, _underscore/Database.php, _underscore/Query.php |
 | [NetSuite ↔ ClickUp / TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Clickup.php, worker2/Worker/Clickup/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, test/@dave/probe_clickup_desc_match.php, test/@dave/test_model_load_behavior.php, dbchanges2/Forecast/2026-06-25a - Add unique index on Opportunities netsuiteOpportunityInternalId.sql, _underscore/Model/Forecast/Opportunity.php, test/@dave/approach/TRUE-80044.md, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)](features/netsuite-salesorder-open-orders-sync.md) | Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). | worker2/Worker/Netsuite/SalesOrder.php, worker2/Worker/Netsuite.php, worker2/Component/Forecast/Db/Db.php, worker2/Worker/Netsuite/Location.php, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/Junk Drawer/NetSuite/api-message-queue/ue_amq_invoice_resync_salesorder.js, test/@dave/probe_salesorder_rest_shape.php, test/@dave/probe_open_order_lines.php, test/@dave/check_so_status.php, test/@dave/check_so_history.php, test/@dave/probe_so_rest_lines.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_open_order_gating.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
+| [Toga → NetSuite Sales-Order Push (multi-client, mapping-driven worker)](features/netsuite-salesorder-outbound-push.md) | The **outbound** half of `worker2/Worker/Netsuite/SalesOrder.php` (everything from the `OUTBOUND PUSH (REST)` banner down) pushes a Toga sales order **into** Ne | worker2/Worker/Netsuite/SalesOrder.php, test/@Bala/tests/netsuite_salesorder_payload_tests.php, worker/crons/toga2/prudential/transmissions_to_netsuite.php |
 | [NetSuite Supporting-Record Webhook Importer (the reusable recipe)](features/netsuite-supporting-record-webhook-importer.md) | A single **repeatable recipe** for porting a legacy daily-pull NetSuite *supporting-record* importer (the lookup/dimension tables behind Forecast2 — Employees, | worker2/Worker/Netsuite/Employee.php, worker2/Worker/Netsuite/Account.php, worker2/Worker/Netsuite/Classification.php, worker2/Worker/Netsuite/Customer.php, worker2/Worker/Netsuite/Item.php, worker2/Worker/Netsuite.php, _underscore/Model/Forecast/Employee.php, _underscore/Model/Forecast/Account.php, _underscore/Model/Forecast/Classification.php, _underscore/Component/Forecast/Db/Db.php, test/@dave/test_employee_lifecycle.php, test/@dave/test_account_lifecycle.php, test/@dave/test_classification_lifecycle.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, worker/crons/toga2/forecast2/import_supporting_records.php |
 | [Background Email-Template Worker (_Worker_Notification_EmailTemplate)](features/notification-email-template.md) | `_Worker_Notification_EmailTemplate::Send(...)` dispatches a **stored, client-defined `EmailTemplates` row off-thread** as a background WorkerJob. | worker2/Worker/Notification/EmailTemplate.php, worker2/Worker/Client/True.php, _underscore/Model/Client/EmailTemplate.php |
 | [DB-Driven Notification (Internal) Email](features/notification-email.md) | Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated, not client-facing transactional mail) are sent through one worker | worker2/Worker/Notification/Email.php, _underscore/Model/Client/EmailTemplate.php, dbchanges2/Client/2026-06-23a - EmailTemplateWrapper.sql, dbchanges2/Client_True/2026-06-23a - EmailTemplateWrapper.sql |

package/knowledge/2.0/apps/worker2/features/creating-worker-actions.md

@@ -6,14 +6,15 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-29
-owners: [jcardinal, dfranks, mhammontree, tcox]
+updated: 2026-08-10
+owners: [jcardinal, dfranks, mhammontree, tcox, bala]
 files:
   - worker2/Worker/
   - worker2/Controller/Index.php
   - _underscore/Worker.php
 related:
   - ../architecture.md
+  - ../../api2/features/api-payload-interceptors.md
 ---
 
 ## Summary
@@ -197,6 +198,31 @@ So **do not design "throw so it retries" — it won't.** To actually retry / sel
 Rule of thumb: `throw` to surface a genuine failure; `runTask`/in-process loop when the work should
 be reattempted.
 
+## `debug_mode` changes how `runTask` dispatches — and the debug path can't do read-after-write
+
+`_Worker::runTask` has two completely different behaviours:
+
+| `debug_mode` | What happens |
+|---|---|
+| `1` | a **synchronous** `_ApiRequest` POST to `_Config::api('worker')` — the action runs **inside the caller's open transaction** |
+| `0` | the job is **enqueued to SQS** and runs later, in another process, on its own connection |
+
+So under debug mode any action that reads back a row the caller just wrote **always fails** (the
+caller hasn't committed). Two related debug-mode side effects to expect: `_Component_Api_Toga` calls
+`$api->debug(true)`, and `ApiRequest.php` **echoes an HTML dump** — which produces
+*"http_response_code(): Cannot set response code - headers already sent"* inside the worker.
+
+### An ABSENT `WorkerJobs` row is ambiguous — don't read it as "never queued"
+
+On the SQS path `runTask` deliberately does **no MySQL work** (stale-connection safety); the
+**worker tier** INSERTs the `WorkerJobs` row on its own connection
+(`worker2/Controller/Index.php` ~L498), using the client-side `uuid` as an idempotency key behind a
+UNIQUE index on `WorkerJobs.uuid`. See [architecture.md](../architecture.md) for the full path.
+
+Debugging consequence: **no row means either "the caller never queued it" or "the message was queued
+and never consumed."** Those have completely different fixes. Distinguish them with the **SQS queue
+metrics**, not the database.
+
 ## Gotchas
 
 - Class must be **`abstract`** and methods **`public static`** or routing fails.
@@ -233,6 +259,14 @@ be reattempted.
   commit-before-SQS transaction pattern that the worker relies on.
 
 ## Change history
+- 2026-08-10 — Documented that **`debug_mode` changes `runTask`'s dispatch** (1 = synchronous
+  `_ApiRequest` POST to `_Config::api('worker')`, running the action inside the caller's open
+  transaction so any read-back fails; 0 = SQS enqueue), plus the debug-mode side effects
+  (`_Component_Api_Toga` calls `$api->debug(true)` and `ApiRequest.php` echoes an HTML dump →
+  *"headers already sent"* in the worker). Added the debugging rule that an **absent `WorkerJobs`
+  row is ambiguous** — the worker tier writes the row (`Controller/Index.php` ~L498, uuid as
+  idempotency key), so "never queued" and "queued but never consumed" look identical in the DB and
+  must be told apart via **SQS queue metrics**. Surfaced building the Elite sales-order push. (bala)
 - 2026-08-06 — Added the **`[database]` vs `[databaseClient]`** gotcha: `Client_*` schemas live on
   the tenant cluster configured in worker2's `Config/*.ini` `[databaseClient]` section, not the core
   `[database]` one (the symptom is a misleading `Unknown database 'Client_Compass'`), and prod's

package/knowledge/2.0/apps/worker2/features/netsuite-salesorder-open-orders-sync.md

@@ -6,8 +6,8 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-24
-owners: ["dfranks"]
+updated: 2026-08-10
+owners: ["dfranks", "bala"]
 files:
   - worker2/Worker/Netsuite/SalesOrder.php
   - worker2/Worker/Netsuite.php
@@ -28,6 +28,7 @@ files:
   - worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php
 related:
   - ./netsuite-opportunity-sync.md
+  - ./netsuite-salesorder-outbound-push.md
   - ../../_underscore/features/netsuite-rest-client.md
   - ../architecture.md
 ---
@@ -78,45 +79,25 @@ separate build (see *Related work*).
    deletes any row NetSuite no longer returns as open (orphans + now-closed lines). Commits
    `DB_FORECAST` (lazy-transaction discipline).
 
-## Outbound push (Toga → NetSuite) — REST-only
-
-The reverse direction (`CreateNetSuite` / `UpdateNetSuite` / `Sync`) pushes a Toga sales order
-*into* NetSuite. As of 2026-06-24 it is **REST-only** via the `_underscore`
-[`_Component_Api_Netsuite`](../../_underscore/features/netsuite-rest-client.md) client — the SOAP
-`NetSuiteService` was fully removed from this file.
-
-- **Item lookup** — SOAP `ItemSearchBasic/search()` → SuiteQL `SELECT id FROM item WHERE itemid =
-  '<part>'`.
-- **Customer resolution** — new `resolveNetSuiteCustomerId()`: prefers mapped
-  `c_netsuiteInternalCustomerId`, else SuiteQL `SELECT id FROM customer WHERE companyname =
-  '<name>'`; **throws on 0 or >1 matches** (never attach the wrong customer — REST has no SOAP
-  RecordRef-by-name resolution).
-- **`buildNetSuiteOrder()`** returns a REST JSON body: `entity:{id}`,
-  `item:{items:[{item:{id},quantity,rate}]}`, **date-only** `tranDate` (`YYYY-MM-DD`; SOAP needed
-  full ISO 8601), `shippingAddress` via `array_filter` dropping null/`''`. `amount` is **omitted**
-  (NetSuite computes it).
-- **Create** → `createRecord()` (reads the new internalId from the 204 `Location` header);
-  **Update** → `send('PATCH', RECORD_SALES_ORDER.'/'.$id, $body)` (204, no body, throws on non-2xx).
-  The SOAP `getNetSuiteErrorDetail()` was removed — REST errors surface as exceptions from
-  `send()`/`createRecord()`.
-- **SuiteQL string escaping** uses a private `escapeSuiteQl()` (`str_replace("'", "''", $value)`),
-  **not** `_Database::escape()` — SuiteQL doubles the quote, so backslash escaping would corrupt
-  `O'Brien`-style names. (See the [REST client doc](../../_underscore/features/netsuite-rest-client.md).)
+## Outbound push (Toga → NetSuite) — documented separately
+
+The reverse direction (`CreateNetSuite` / `UpdateNetSuite` / `Sync`) lives in the **same file** but is
+a **separate subject with its own doc**:
+[Toga → NetSuite Sales-Order Push](./netsuite-salesorder-outbound-push.md). It went REST-only on
+2026-06-24 (SOAP `NetSuiteService` fully removed from this file) and was rebuilt on 2026-08-10 as a
+multi-client, mapping-driven worker.
+
+**The two halves share no code, constants or helpers** (verified 2026-08-10: this inbound half's
+2,231 executable tokens are byte-identical to `origin/_production` after the outbound rebuild). Read
+the outbound doc before touching anything below the `OUTBOUND PUSH (REST)` banner — and don't assume
+a change there affects the import.
+
 - **Blast radius isolated.** Two other worker2 files still use SOAP and each construct their own
   `NetSuiteService` (`Worker/Ai/Bdr/Netsuite.php`, `Worker/Client/Aig/ClosedClaims.php`) — untouched;
   `library/netsuitetoolkit` stays loaded for worker2.
 
-### Refactor (2026-06-24)
-
-- `fetchSalesOrder()` 4 positional params → `(array $clientContext, int $salesOrderId)` per the
-  TOGA 4-param rule (4+ positional must become an assoc-array/named-params signature; PHP named
-  *arguments* at the call site do **not** satisfy the rule — it targets the **signature**).
-- **`Sync()` double-fetch fixed.** `Sync` previously re-ran `getClientContext()` + `fetchSalesOrder()`
-  and then called Create/Update, which fetched **again** (2× Core DB + 2× Toga API per Sync). It now
-  fetches **once** and delegates to private `doCreate(array,object,int)` / `doUpdate(object,int)`;
-  the public `CreateNetSuite`/`UpdateNetSuite` are thin fetch-then-delegate wrappers (public
-  action-router contract unchanged). Closes a small **TOCTOU** — the open/close decision and the
-  write now use the same fetched record.
+The 2026-06-24 outbound refactor notes (the `fetchSalesOrder()` 4-param signature rule and the
+`Sync()` double-fetch/TOCTOU fix) moved to that doc as well.
 
 ## Data model
 
@@ -415,6 +396,12 @@ test fixture (it surfaced the stale SO 7181316 above).
 
 ## Change history
 
+- 2026-08-10 — **Split the outbound push (Toga → NetSuite) out into its own doc**
+  ([netsuite-salesorder-outbound-push](./netsuite-salesorder-outbound-push.md)) when it was rebuilt as
+  a multi-client mapping-driven worker; this doc now covers the **inbound** import only. Verified the
+  inbound half is byte-identical to `origin/_production` (2,231 executable tokens) and that the two
+  halves share no code, constants or helpers. The 2026-06-24 outbound refactor notes moved with it.
+  (bala)
 - 2026-07-24 — **Resolved the open questions on the OpenOrderItems location / amountDue Power-BI
   backfill (investigation + planning).** `locationId` is NULL because `Forecast.Locations` is
   unpopulated and `resolveLocationId` (`worker2/Component/Forecast/Db/Db.php`) has no self-heal on a

package/knowledge/2.0/apps/worker2/features/netsuite-salesorder-outbound-push.md

@@ -0,0 +1,159 @@
+---
+title: Toga → NetSuite Sales-Order Push (multi-client, mapping-driven worker)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-08-10
+owners: ["bala"]
+files:
+  - worker2/Worker/Netsuite/SalesOrder.php
+  - test/@Bala/tests/netsuite_salesorder_payload_tests.php
+  - worker/crons/toga2/prudential/transmissions_to_netsuite.php
+related:
+  - ./netsuite-salesorder-open-orders-sync.md
+  - ./creating-worker-actions.md
+  - ../../_underscore/features/netsuite-rest-client.md
+  - ../../api2/features/api-payload-interceptors.md
+  - ../../../clients/elite/features/salesorder-netsuite-push.md
+---
+
+## Summary
+
+The **outbound** half of `worker2/Worker/Netsuite/SalesOrder.php` (everything from the
+`OUTBOUND PUSH (REST)` banner down) pushes a Toga sales order **into** NetSuite over REST. As of
+2026-08-10 it is a **single multi-client worker**: every NetSuite id it needs is resolved by
+following the order's own foreign keys to that record's `c_netsuite*` mapping column, so **nothing
+is hardcoded per client**. It replaces the 1.0 per-client cron pattern
+(`worker/crons/toga2/prudential/transmissions_to_netsuite.php`), which hardcoded one client's
+ids and ran on a timer.
+
+The **inbound** NetSuite → Forecast open-orders import lives in the *same file* but is a separate
+subject and was not changed — see
+[NetSuite → Forecast Open-Orders Sync](./netsuite-salesorder-open-orders-sync.md). The two halves
+share no code, constants or helpers (verified 2026-08-10: the inbound half's 2,231 executable
+tokens are identical to `origin/_production`). **Edit one without assuming anything about the
+other.**
+
+## Key files / entry points
+
+| Action | Method | Purpose |
+|---|---|---|
+| `Netsuite/SalesOrder/CreateNetSuite` | `CreateNetSuite` | create the order in NetSuite, write the id back |
+| `Netsuite/SalesOrder/UpdateNetSuite` | `UpdateNetSuite` | PATCH an already-synced order |
+| `Netsuite/SalesOrder/Sync`           | `Sync`           | create-or-update in one call |
+
+All three share one signature — **the parameter names are the queue contract** (the dispatcher
+spreads `parameters` as named arguments):
+
+```
+(string $clientIdentifier, string $salesOrderUuid, bool $dryRun = false, ?object $salesOrder = null)
+```
+
+Supporting privates: `getClientContext`, `fetchSalesOrder`, `buildNetSuiteOrder`,
+`resolveNetSuiteCustomerId`, `resolveNetSuiteItemId`, `runSuiteQl`, `escapeSuiteQl`,
+`assertOrderMatchesUuid`, `doCreate`, `doUpdate`. Constants: `SUITEQL_ITEM_TYPE__GROUP = 'Group'`,
+`TOGA_FETCH_DEPTH = 4`.
+
+## How it works
+
+1. `getClientContext($clientIdentifier)` resolves the tenant — the client is a **parameter**, not a
+   per-client class or cron.
+2. The order is either **carried in the job** (`$salesOrder`, see below) or fetched by uuid via
+   `fetchSalesOrder` at `TOGA_FETCH_DEPTH = 4`.
+3. `assertOrderMatchesUuid()` runs **first** in both `doCreate` and `doUpdate` — before the dry-run
+   branch and before the already-synced check — so a job carrying the wrong order is reported as a
+   mismatch rather than as a misleading "already synced".
+4. `buildNetSuiteOrder()` assembles the REST body. Every NetSuite id — **customer, item, location,
+   shipping method** — is resolved by walking the order's own foreign keys to that related record's
+   `c_netsuite*` mapping column; where a value must be looked up in NetSuite instead,
+   `runSuiteQl()` does it (string literals escaped with `escapeSuiteQl()` — SuiteQL **doubles** the
+   quote, `''`, it never backslashes it).
+5. **A missing customer / item / location mapping aborts the whole order** rather than sending a
+   partial one. A missing **shipping method** is simply omitted so NetSuite applies its default.
+6. Create → `_Component_Api_Netsuite::createRecord()` (id from the 204/201 `Location` header);
+   update → `send('PATCH', …)`. The new internalId is written back to
+   `SalesOrders.c_netsuiteInternalSalesOrderId`.
+7. `dryRun = true` builds and returns the payload without calling NetSuite.
+
+### The job carries the order snapshot — the worker does not re-read it
+
+`$salesOrder` lets the **caller** (an api2 post interceptor) pass the already-read order object
+along in the job parameters, so the worker never re-reads it from MySQL. This is deliberate and
+load-bearing: the interceptor runs inside api2's still-open transaction, so a worker in another
+process (on a **reader** connection) cannot see the new row at all. See
+[API Payload Interceptors → queueing background work](../../api2/features/api-payload-interceptors.md).
+
+**Rejected alternatives (2026-08-10):**
+- **A bounded retry loop in the worker** — fragile and timing-dependent; it papers over the
+  visibility problem instead of removing it.
+- **Copying Prudential's "pass `$payload` straight through" pattern** — the POST body contains only
+  uuids, while NetSuite needs the resolved `c_netsuite*` ids; and at depth 3
+  `shipToAddress.state.country` is omitted entirely (country sits four levels down: order →
+  shipToAddress → state → country), which breaks non-US orders. Hence `TOGA_FETCH_DEPTH = 4`.
+- **Pushing synchronously from the interceptor** — a NetSuite create takes **~12s** (measured); it
+  can never be atomic with the MySQL commit anyway, and holding a transaction open across a 12s
+  external call risks row locks and dropped connections. The push stays **async**.
+
+## Earlier history worth keeping (2026-06-24, moved from the inbound doc)
+
+- **REST-only since 2026-06-24** — the SOAP `NetSuiteService` was fully removed from this file. Item
+  lookup went from SOAP `ItemSearchBasic/search()` to SuiteQL `SELECT id FROM item WHERE itemid = …`;
+  `tranDate` is **date-only** (`YYYY-MM-DD`; SOAP needed full ISO 8601); `amount` is **omitted** so
+  NetSuite computes it; `shippingAddress` is `array_filter`ed to drop null/`''`. SOAP's
+  `getNetSuiteErrorDetail()` is gone — REST errors surface as exceptions from
+  `send()`/`createRecord()`.
+- **`fetchSalesOrder()` was reduced from 4 positional params** to `(array $clientContext, int
+  $salesOrderId)` per the TOGA 4-param rule — 4+ positional parameters must become an
+  assoc-array/named-params **signature**; PHP named *arguments* at the call site do **not** satisfy
+  the rule.
+- **`Sync()`'s double fetch was removed:** it used to re-run `getClientContext()` +
+  `fetchSalesOrder()` and then call Create/Update, which fetched again (2× Core DB + 2× Toga API per
+  Sync). It now fetches once and delegates to the private `doCreate`/`doUpdate`, with
+  `CreateNetSuite`/`UpdateNetSuite` as thin wrappers — which also closed a TOCTOU, since the decision
+  and the write now use the same fetched record.
+
+## Test harness (76 tests, all passing)
+
+`test/@Bala/tests/netsuite_salesorder_payload_tests.php` loads the **real** worker file with
+stubbed dependencies and drives the private methods by **reflection**, so it tests shipped code
+rather than a copy (same technique as
+[DB-free interceptor unit testing](../../_underscore/features/model-interceptor-unit-testing.md)).
+Coverage: header fields, mapping resolution, SuiteQL quote-doubling, missing-mapping aborts, dry
+run, create, update, the job-carried-snapshot path, and the uuid-match guard.
+
+## Gotchas / known issues
+
+- **⚠ A crash *after* the NetSuite create leaves an orphan.** `createRecord()` reads the `Location`
+  header after NetSuite has already created the record, so any failure past that point (the
+  `#`-delimiter regex bug did exactly this — see the
+  [REST client doc](../../_underscore/features/netsuite-rest-client.md)) leaves a live NetSuite
+  order with **nothing in Toga pointing at it**. Two Elite orders were orphaned in NetSuite account
+  1095849 this way. **Never blind-retry a failed create** — check NetSuite for the record first.
+- **This action does not retry itself.** Worker actions have no DLQ and no auto-retry: a throw
+  records `isSuccess = 0` and stops. Unlike the 1.0 cron it replaces (which re-selected unsent
+  orders every tick and was therefore self-healing), an event-triggered push fires **once**. Pair
+  it with a monitor on orders whose `c_netsuiteInternalSalesOrderId` is still NULL — see the
+  [Elite client-feature](../../../clients/elite/features/salesorder-netsuite-push.md).
+- **`$dryRun` and `$salesOrder` are optional but positional-by-name.** Callers must pass them as
+  named keys in `parameters`; a caller that sends a differently-named key gets
+  *"Unknown named parameter"* from the dispatcher — which on a stale instance looks like a code bug
+  rather than a deploy problem (see the
+  [deploy workflow](../../api2/workflows/codepipeline-codeconnections-deploy.md)).
+- **The inbound importer in this file is untouched and unrelated.** Do not "tidy" shared-looking
+  helpers across the banner; there are none.
+
+## Change history
+
+- 2026-08-10 — **Rebuilt the outbound push as a single multi-client, mapping-driven worker**
+  (`CreateNetSuite` / `UpdateNetSuite` / `Sync`, signature
+  `(clientIdentifier, salesOrderUuid, dryRun, salesOrder)`), replacing the per-client 1.0 cron
+  pattern: every NetSuite id resolves through the order's own FKs to `c_netsuite*` columns, a
+  missing customer/item/location mapping **aborts** the order, a missing shipping method is
+  omitted. Added the **job-carried order snapshot** (`?object $salesOrder`, `TOGA_FETCH_DEPTH = 4`
+  so `shipToAddress.state.country` is present) and the `assertOrderMatchesUuid()` guard from code
+  review. Recorded the rejected alternatives (worker retry loop, Prudential's payload
+  pass-through, synchronous push — a NetSuite create measures ~12s) and the 76-test reflection
+  harness. Split out of the inbound open-orders doc, which now points here. (bala)

package/knowledge/2.0/apps/worker2/features/netsuite-supporting-record-webhook-importer.md

@@ -6,8 +6,8 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-30
-owners: ["dfranks"]
+updated: 2026-08-10
+owners: ["dfranks", "bala"]
 files:
   - worker2/Worker/Netsuite/Employee.php
   - worker2/Worker/Netsuite/Account.php
@@ -114,9 +114,18 @@ recipe and its two recurring variants so a new one is a fill-in-the-blanks job,
   no migration needed.
 - **`save()` does not diff** — see recipe step 2: the change-detect guard before `save()` is what makes
   a no-change webhook a true no-op.
+- **⚠ Unrelated observation, production, 2026-08-10: three of these job types are at 0% success and
+  nobody is watching.** `Core.WorkerJobs` in prod shows `Netsuite/InventoryItem/post` (266 jobs),
+  `Netsuite/InventoryItem/put` (1,014) and `Netsuite/ItemGroup/post` (5) with **zero successes**, and
+  they are still firing daily. Recorded here as a flag for whoever owns these importers — it was not
+  investigated (surfaced incidentally while auditing WorkerJobs for the Elite sales-order push).
 
 ## Change history
 
+- 2026-08-10 — Flagged a **production health observation** (not investigated): prod `Core.WorkerJobs`
+  has `Netsuite/InventoryItem/post` (266), `Netsuite/InventoryItem/put` (1,014) and
+  `Netsuite/ItemGroup/post` (5) at **0% success**, still running daily and apparently unmonitored.
+  Surfaced incidentally while auditing WorkerJobs for the Elite sales-order push. (bala)
 - 2026-06-30 — Captured the supporting-record webhook-importer recipe and its two variants
   (self-ref RESOLVE-OR-NULL parent FK + child-orphan delete-guard; Accounts `accttype` enum map; leaf
   segment naming) after the third+ application (TRUE-79870 Employees, TRUE-79871 Accounts, TRUE-79872

package/knowledge/INDEX.md

@@ -18,8 +18,8 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 49 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 44 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 50 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **worker2** (Worker) — 45 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 22 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 8 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 5 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

package/knowledge/clients/elite/INDEX.md

@@ -2,6 +2,7 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
+| [Elite SalesOrder → NetSuite Push (postPost/postPut interceptors → worker2)](features/salesorder-netsuite-push.md) | 2.0 | Elite orders created in Toga are pushed into NetSuite **event-driven**, not on a cron. | _underscore/Model/Elite/SalesOrder.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Client_Elite/2026-08-10 - SalesOrderNetsuiteInterceptors.sql |
 | [Elite — supply2 frontend scope (Inventory + Service Requests, both built)](features/supply2-scope.md) | 2.0 | Scope for onboarding Elite to the `toga2-supply` frontend (host `ELITE`). | toga2-supply/ELITE-CLIENT-TASK-NOTES.md, toga2-supply/src/pages/Inventory/viewModel/FIELDS/DUMMYGROUPOPTIONS.ts, toga2-supply/src/pages/Inventory/viewModel/FIELDS/INVENTORYPAGEFIELDS.ts, toga2-supply/src/pages/Inventory/viewModel/index.ts, toga2-supply/src/pages/Inventory/listing/InventoryPage.tsx, toga2-supply/src/pages/Inventory/listing/InventoryRouter.tsx, toga2-supply/src/pages/Inventory/listing/InventorySubTablePage.tsx, toga2-supply/src/utils/resolveClientHostName.ts, toga2-supply/src/utils/convertConstructorColumnTitles.ts, toga2-supply/src/pages/Orders/OrdersPage.tsx, toga2-supply/src/pages/Orders/viewModel/FIELDS/ELITE/BASE.json, toga2-supply/src/pages/Orders/viewModel/useOrdersPageViewModel.ts, toga2-supply/src/pages/Orders/api/OrdersApi.ts, toga2-supply/src/pages/Orders/view/OrderView/viewModel/useOrderDetailsViewModel.ts, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/renderModalContent.tsx, toga2-supply/src/components/layout/SlideMenu/SlideMenu.tsx, toga2-supply/package.json |
 | [Elite — stale TableView config (11 dead Core.RecordFields across 9 views)](features/supply2-tableview-config-drift.md) | 2.0 | `Client_Elite`'s `TableViewJoins` predate **two** platform bridge-table migrations and still reference **11 deleted `Core.RecordFields` ids (211, 321, 932, 358, | dbchanges2/Client_Elite/, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql |
-| [Elite](profile.md) | 2.0 | Elite is a managed-services client that uses **Freshservice** as their helpdesk platform. | worker2/Worker/Elite.php, library/app/api/toga2.php |
+| [Elite](profile.md) | 2.0 | Elite is a managed-services client that uses **Freshservice** as their helpdesk platform. | worker2/Worker/Elite.php, library/app/api/toga2.php, _underscore/Model/Elite/SalesOrder.php |

package/knowledge/clients/elite/features/salesorder-netsuite-push.md

@@ -0,0 +1,121 @@
+---
+title: "Elite SalesOrder → NetSuite Push (postPost/postPut interceptors → worker2)"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: elite
+type: client-feature
+status: active
+updated: 2026-08-10
+owners: ["bala"]
+files:
+  - _underscore/Model/Elite/SalesOrder.php
+  - worker2/Worker/Netsuite/SalesOrder.php
+  - dbchanges2/Client_Elite/2026-08-10 - SalesOrderNetsuiteInterceptors.sql
+related:
+  - ../../../2.0/apps/worker2/features/netsuite-salesorder-outbound-push.md
+  - ../../../2.0/apps/api2/features/api-payload-interceptors.md
+  - ../../../2.0/apps/_underscore/features/netsuite-rest-client.md
+  - ../profile.md
+---
+
+## Summary
+
+Elite orders created in Toga are pushed into NetSuite **event-driven**, not on a cron.
+`_Model_Elite_SalesOrder::postPost` queues the worker action
+`Netsuite/SalesOrder/CreateNetSuite` when an order is created, and `postPut` queues
+`UpdateNetSuite` when the **shipping method** changes. The worker itself is the shared,
+client-agnostic push documented in
+[Toga → NetSuite Sales-Order Push](../../../2.0/apps/worker2/features/netsuite-salesorder-outbound-push.md) —
+Elite contributes only the trigger and the interceptor registration data.
+
+This is Elite's override of the shared push path; it is the second client on that path (Rate uses a
+different shape — a CashSale built inline in `postPost`).
+
+## How it works
+
+1. **`postPost`** calls `parent::postPost()` **first** (so approval records are still created),
+   then reads the order for NetSuite and queues `Netsuite/SalesOrder/CreateNetSuite`.
+2. **`postPut`** does the same and queues `Netsuite/SalesOrder/UpdateNetSuite`, but only when the
+   shipping method changed.
+3. **Both bail immediately when `$api->httpPayload->c_netsuiteInternalSalesOrderId` is set** — such
+   an order arrived **from** NetSuite via the inbound sync and must not be echoed back.
+4. The private `readSalesOrderForNetsuite()` reads the order **inside the same request** via
+   `$api->internalApiRequest()`, pinned to the writer, and the resulting order object is passed
+   along in the job parameters so the worker never re-reads it. The full set of timing /
+   read-replica / envelope rules that make this correct is documented once, in
+   [API Payload Interceptors → queueing background work from a post interceptor](../../../2.0/apps/api2/features/api-payload-interceptors.md).
+5. `runTask` is wrapped in `try/catch` + `error_log`, so a broken queue can never fail the sales
+   order POST itself.
+
+## Interceptor registration is per-environment DATA — and prod has none
+
+`Client_Elite.ApiPayloadInterceptors` is **EMPTY in production**. Without rows, `postPost`/`postPut`
+**never run**: the order saves, nothing else happens, and there is no error anywhere. The
+migration `dbchanges2/Client_Elite/2026-08-10 - SalesOrderNetsuiteInterceptors.sql` registers
+`POST`/`POST` and `POST`/`PUT` for **`recordId 14` (sales-orders)**, guarded with
+`WHERE NOT EXISTS` so a replay cannot create duplicates — **a duplicate row would queue the same
+NetSuite job twice for one order.** (Check the file carries dbchanges2's mandatory
+`YYYY-MM-DD<letter>` suffix before it merges.)
+
+`recordId 14` and the `Apis` ids (**1 = Agilant, 2 = Elite**) happen to match between dev-sandbox
+and production — **verify them per environment rather than assuming.**
+
+## Current production state (2026-08-10)
+
+- **264 Elite sales orders; 258 carry a NetSuite id, 6 do not.**
+- **No order has yet completed the full interceptor → SQS → worker → NetSuite path end to end.**
+  The furthest run (`WorkerJobs 22743`) queued correctly **with** the order snapshot and with
+  `shipToAddress.state.country = CA` present, then failed on a **stale SQS-consumer instance**
+  (see the [deploy workflow](../../../2.0/apps/api2/workflows/codepipeline-codeconnections-deploy.md)).
+- One order was created in NetSuite successfully by **direct worker invocation**
+  (`WorkerJobs 22452`): NetSuite id **7358493** written back to `SalesOrders.259`.
+- **Two orphaned Elite orders exist in live NetSuite account 1095849** from the `createRecord()`
+  regex bug — created in NetSuite with nothing in Toga pointing at them.
+
+## What the existing production precedent does and does not prove
+
+The interceptor → `runTask` → SQS → worker2 chain **is** proven at volume in production
+(`Core.WorkerJobs`): `Notification/EmailTemplate/Send` 1091/1091 succeeded and
+`Client/Prudential/reports/ReqRejectionEmail/sendRejectionEmail` 20/20 — both queued from
+interceptors. worker2 ↔ NetSuite is healthy too: `Netsuite/SalesOrder/put` 35,259 jobs / 35,220
+succeeded; `Netsuite/Webhook` 46,273 / 46,207.
+
+**What Prudential does NOT prove:** it passes `$payload` straight through and never reads back, so
+the **in-transaction read + writer-pinning** this feature depends on has **no production
+precedent**. Treat the first prod Elite order as a real first run.
+
+## Gotchas / known issues
+
+- **⚠ No retry safety net — this is the structural difference from the 1.0 cron.** The 1.0
+  Prudential cron selected on `PurchaseOrders.dtSubmitted IS NULL`, so a failed run healed itself
+  on the next tick. An interceptor fires **once**; a failed push leaves an order with
+  `c_netsuiteInternalSalesOrderId IS NULL` and **nothing watching**.
+  **Recommended follow-up (NOT built): an alert-only monitor** on orders older than ~15 minutes
+  that are still NULL. A **blind retry sweeper was deliberately rejected** — a previous attempt may
+  have created the NetSuite order and only failed the write-back, so retrying would duplicate.
+- **⚠ A missing `ApiPayloadInterceptors` row is silent.** "The push didn't happen" in a given
+  environment is a **data** question first (`SELECT` the client's interceptor rows), never a code
+  question.
+- **api2's `error_log()` output is not in CloudWatch.** worker2 ships
+  `/var/log/php-fpm/www-error.log` to the `worker` log group via a postdeploy hook; **api2 has no
+  equivalent hook**, so the interceptor's silent-skip messages must be pulled from the EB
+  request/full logs.
+- **Orders that arrived from NetSuite must not be pushed back** — the
+  `c_netsuiteInternalSalesOrderId`-on-payload bail is what prevents an echo loop. Keep it in any
+  new hook on this model.
+
+## Change history
+
+- 2026-08-10 — **Built the Elite push trigger**: `_Model_Elite_SalesOrder::postPost` queues
+  `Netsuite/SalesOrder/CreateNetSuite`, `postPut` queues `UpdateNetSuite` on a shipping-method
+  change; both call `parent::postPost()` first, bail when the payload carries
+  `c_netsuiteInternalSalesOrderId` (order came from the inbound sync), read the order in-request via
+  `internalApiRequest` (writer-pinned) and pass the snapshot in the job, and wrap `runTask` in
+  try/catch so a queue failure cannot fail the POST. Added
+  `dbchanges2/Client_Elite/2026-08-10 - SalesOrderNetsuiteInterceptors.sql` (recordId 14, POST/POST
+  + POST/PUT, `NOT EXISTS`-guarded) because **`Client_Elite.ApiPayloadInterceptors` is empty in
+  prod**. Recorded the missing retry safety net vs. the 1.0 cron (alert-only monitor recommended;
+  blind retry sweeper rejected — duplicate risk), the two orphaned NetSuite orders in account
+  1095849, and the current state: 264 orders / 258 with a NetSuite id, no end-to-end run yet
+  (NetSuite 7358493 created by direct worker invocation). (bala)

package/knowledge/clients/elite/profile.md

@@ -6,20 +6,24 @@ apps:
   - library
   - toga2-supply
   - dbchanges2
+  - _underscore
+  - api2
 project: Worker
 client: elite
 type: profile
 status: active
 updated: 2026-08-10
-owners: [snaredla, apeterson, tcox]
+owners: [snaredla, apeterson, tcox, bala]
 files:
   - worker2/Worker/Elite.php
   - library/app/api/toga2.php
+  - _underscore/Model/Elite/SalesOrder.php
 related:
   - 2.0/apps/worker2/features/elite-freshservice-sync.md
   - 1.0/apps/library/features/elite-freshservice-sync.md
   - features/supply2-scope.md
   - features/supply2-tableview-config-drift.md
+  - features/salesorder-netsuite-push.md
 ---
 
 ## Summary
@@ -42,6 +46,12 @@ view is built on (joining Tickets / Customers / ServiceRequestTypes / SalesOrder
 dev-sandbox have no linked sales order** — whether that is a legitimate lifecycle state is an open
 question for backend/product (see supply2-scope).
 
+**Elite orders are pushed to NetSuite event-driven (2026-08).** `_Model_Elite_SalesOrder`'s
+`postPost`/`postPut` interceptors queue the shared worker2 push. Elite's
+`ApiPayloadInterceptors` table is **empty in production**, so the registration migration is the
+go-live gate — see [salesorder-netsuite-push](features/salesorder-netsuite-push.md). This work adds
+**`_underscore`** and **`api2`** to Elite's app scope.
+
 **Tenant/test-account notes.** `Core.Domains` rows for Elite already exist in **every**
 environment (dev `http://elite.togasupply`, beta, production, sandbox-dev) with no dbchanges2 Core
 migration creating them, and Elite has **no `ClientAuthentications` row** — supply2 login is

package/package.json

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