toga-ai 1.0.744 → 1.0.745

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

@@ -10,6 +10,7 @@
 | [_ApiRequest — JSON encode/decode & api-logging behavior](features/apirequest-json-content-type.md) | `_ApiRequest` is the 2.0 outbound HTTP client. | _underscore/ApiRequest.php |
 | [Assortment Name Translation (AssortmentTranslations sidecar)](features/assortment-name-translation.md) | Serves Assortment (product-grouping) **names** in multiple languages by adding a per-language **sidecar** table `AssortmentTranslations`, reusing the platform's | _underscore/Model/Client/AssortmentTranslation.php, dbchanges2/Client/2026-06-26a - AssortmentTranslations.sql, dbchanges2/Core/2026-06-26a - AssortmentTranslationsRecord.sql, dbchanges2/Client/2026-06-26b - AssortmentTranslationsAcl.sql |
 | [Asynchronous Query Execution (writes-only, via Worker)](features/async-query-execution.md) | `_Query` can run a **write** query asynchronously so a long/slow write does not hold a request-scoped DB connection open long enough to hit **"MySQL server has | _underscore/Query.php, worker2/Worker/Infrastructure/Database.php, worker2/Worker/Team/Transcripts.php |
+| [FIELD_AUTOINCREMENT record numbering (SA / TA prefixes, NULL-only trigger, no padding)](features/autoincrement-record-numbering.md) | A human-facing record number (`SA100001`, `TA100000`) is generated by the ORM, not by MySQL. | _underscore/Model.php, _underscore/Model/Client/SalesOrder.php, _underscore/Model/Client/TransferOrder.php |
 | [FIELD_SQL calculated fields — the underscore-prefix + same-name-method contract](features/calculated-sql-fields.md) | A `FIELD_SQL` (calculated) field on a `_Model` is bound by a **two-part contract that `_Model` enforces by throwing at model-construction time**, not by convent | _underscore/Model.php, _underscore/Model/Client/PurchaseOrder.php, _underscore/Model/Client/SalesOrder.php, _underscore/Model/Client/ServiceRequest.php, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/Canada/SalesOrder.php, api2/Component/Api/V2/V2.php, _underscore/Model/Quad/Item.php, _underscore/Model/Quad/VendorItem.php, dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql, dbchanges2/Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql |
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | test/@Mark/true-80824-fedex-inflate-test.php, dbchanges2/Client_Growrk/2026-08-10e - GrowrkUpsServiceMethodCodes.sql, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/ShipmentRequest/ShipmentRequest.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.php, _underscore/Component/Library/Carriers/Usps/Usps.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [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 |

package/knowledge/2.0/apps/_underscore/features/autoincrement-record-numbering.md

@@ -0,0 +1,96 @@
+---
+title: "FIELD_AUTOINCREMENT record numbering (SA / TA prefixes, NULL-only trigger, no padding)"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-09-02
+owners: ["bala"]
+files:
+  - _underscore/Model.php
+  - _underscore/Model/Client/SalesOrder.php
+  - _underscore/Model/Client/TransferOrder.php
+related:
+  - ../architecture.md
+  - ../../worker2/features/netsuite-transferorder-outbound-push.md
+  - ../../worker2/features/netsuite-salesorder-outbound-push.md
+---
+
+## Summary
+
+A human-facing record number (`SA100001`, `TA100000`) is generated by the ORM, not by MySQL. A model
+declares it as `FIELD_AUTOINCREMENT` with two options:
+
+```php
+public $number = [
+	self::FIELD_AUTOINCREMENT,
+	self::FIELDOPT_AUTOINCREMENT_PREFIX => 'TA',
+	self::FIELDOPT_AUTOINCREMENT_FIRSTNUMBER => 100000,
+];
+```
+
+`_Model_Client_SalesOrder` uses `SA` / 100000; `_Model_Client_TransferOrder` was given `TA` / 100000
+on 2026-09-02, on the **shared** client model, so every client's transfer orders get it.
+
+## How it works (verified in `_underscore/Model.php` ~L546)
+
+1. **The generator only fires when the field arrives NULL** (`if (is_null($value))`). **A supplied
+   number always wins.** That is what makes an importer that sends its own number (the NetSuite
+   importer sends `number = $nsOrder->tranId`) completely unaffected by adding the option — and it is
+   also why a front-end that still posts `"number": "286906"` means the generator **never runs**.
+2. **The next value is `MAX(numeric part) + 1` scoped by `WHERE number LIKE '<prefix>%'`.** So
+   pre-existing numbers in another format are ignored: NYCHH's 1,930 legacy transfer-order numbers
+   (e.g. `286906`) do not participate, and the sequence starts clean at `TA100000`.
+3. **There is NO zero padding.** The output is prefix + integer, so `TA00000` is not achievable
+   without changing `Model.php`.
+
+## ⚠ A prefix on a SHARED model is not unique across clients
+
+Because the option lives on `_Model_Client_TransferOrder`, **every tenant starts at `TA100000`** —
+the scan is per client database. Any cross-client identifier must therefore **not** be keyed on
+`number`:
+
+- NetSuite account **1095849 is shared by every client** and enforces `externalId` uniqueness
+  account-wide, which is why both pushes key their external id on the record **uuid**
+  (`toga-so-<uuid>` / `toga-to-<uuid>`) — see
+  [the transfer-order push](../../worker2/features/netsuite-transferorder-outbound-push.md).
+
+## A generated number can be a PLACEHOLDER — decide its lifetime explicitly
+
+`SA`/`TA` numbers are **overwritten by NetSuite's `tranId`** on write-back, so the generated value
+lives about 12 seconds. That is the intended behaviour for both order types, but it makes `number` a
+**moving value** — never build a key, a match, or an external id on it.
+
+**Keeping a Toga-side number permanently takes TWO changes, not one** (written 2026-09-02, then
+**reverted** at the developer's request — recorded so nobody rediscovers it):
+
+1. a guard in `writeBackNetSuiteId()` so the push does not overwrite `number`, **and**
+2. dropping `number` from the PUT in **both** `library/app/api/toga2.php` (~L4295) and
+   `_underscore/Trait/Netsuite/TransferOrder.php`.
+
+Miss (2) and the 1.0 importer compares `number` and PUTs NetSuite's over the top on its next run, so
+the guard alone achieves nothing. Both files are back to untouched (verified with an empty
+`git diff`).
+
+## Gotchas / known issues
+
+- **`FIELD_AUTOINCREMENT` is one of the field types special-cased by `buildSqlFieldValue()`**, so a
+  null value on it does **not** collapse a `load()` WHERE clause the way a null `FIELD_CHAR` does —
+  see the collapsed-WHERE OOM note in [_underscore architecture](../architecture.md).
+- **Adding the option to a model does not renumber anything** and does not touch existing rows; it
+  only affects inserts that arrive with `number` NULL.
+- **A front-end that sends `number` silently disables the feature.** There is no error — the posted
+  value is simply accepted. Check the actual POST body before concluding the generator is broken.
+
+## Change history
+
+- 2026-09-02 — Documented `FIELD_AUTOINCREMENT` numbering while giving
+  `_Model_Client_TransferOrder.number` a `TA` / 100000 sequence (mirroring `SalesOrder`'s `SA`) on the
+  **shared** client model: the generator fires **only** on a NULL value, the next number is
+  `MAX(numeric) + 1` scoped by `number LIKE '<prefix>%'` (so 1,930 legacy NYCHH numbers are ignored),
+  and there is **no zero padding**. Recorded that a shared-model prefix is not unique across tenants
+  (every client starts at `TA100000`), so cross-client keys must use the uuid; and that keeping a
+  Toga-side number permanently needs **both** a `writeBackNetSuiteId` guard and dropping `number`
+  from the 1.0 importer's PUT — written and then reverted. (bala)

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

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-08-10
+updated: 2026-09-02
 owners: ["mhammontree", "bala"]
 files:
   - _underscore/Config.php
@@ -92,6 +92,32 @@ the two keys to `beta.ini` and `sandbox-dev.ini`.
 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.
 
+## Do NOT move a correctness-critical constant into the ini (rejected suggestion, 2026-09-02)
+
+A code-review bot (CodeRabbit) proposed moving `const NETSUITE_READ_DEPTH = 4` out of
+`_Model_Client_TransferOrder` and into `Config/<environment>.ini` behind `_Config`. **Rejected**, and
+the reasoning generalises:
+
+1. **It is not a setting, it is a fact about the data shape.** The value the code needs sits three
+   FK hops out (`transferOrder` → `purchaseOrdersTransferOrders` → `purchaseOrder` → `number`), so 4
+   is the *minimum* depth that returns it — and at 3 the value comes back **missing with no error**.
+   A knob whose only correct value is a property of the query is not configuration.
+2. **The ini is per environment, so it invites exactly the drift class we already fight** — a depth
+   that differs between prod, beta and sandbox (see
+   [non-prod metadata drift](../../dbchanges2/workflows/nonprod-metadata-drift-repair.md)).
+3. **Precedent is in code:** `_Worker_Netsuite_SalesOrder::TOGA_FETCH_DEPTH = 4` is a class constant
+   and `_Model_Elite_SalesOrder` hardcodes `'depth' => 4` inline.
+4. **The suggested call did not even exist.** `_Config` has **no `group()` method** — it dispatches
+   through `__callStatic`, so it would have been `_Config::netsuite('readDepth')`, which **throws on a
+   missing key** (`Config.php` ~L79). An uncaught throw from a `postPost` interceptor returns
+   **HTTP 500 `EO-1` and rolls the write back**, so the "cleanup" would have let a one-line ini edit
+   take the transfer-order write endpoint down.
+
+> **General rule: a depth/shape constant that a query's correctness depends on stays in code.** Move
+> to the ini only what genuinely varies by environment (hosts, credentials' location, feature tiers).
+> And when a review suggests a `_Config` call, check the method exists — a plausible-looking
+> `_Config::group('x')` is not part of this API.
+
 ## Gotchas / known issues
 
 - **`_Config::<group>('prop', false)` is NOT a null-safe read.** It is property-optional only.
@@ -106,6 +132,14 @@ reads** — the group existing proves nothing.
 
 ## Change history
 
+- 2026-09-02 — Recorded a **rejected** code-review suggestion to move
+  `_Model_Client_TransferOrder::NETSUITE_READ_DEPTH = 4` into `Config/<environment>.ini`: the value is
+  a fact about the read shape (the PO number sits 3 FK hops out; at depth 3 it returns **missing with
+  no error**), the ini is per environment so it would invite drift, precedent (`TOGA_FETCH_DEPTH`,
+  Elite's inline `'depth' => 4`) keeps it in code, and the suggested API does not exist —
+  `_Config` has **no `group()`**, it uses `__callStatic`, and a missing key **throws**, which from a
+  `postPost` interceptor is a 500 `EO-1` with the write rolled back. **General rule: a depth/shape
+  constant a query's correctness depends on stays in code.** (bala)
 - 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` /

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, api2/Controller/Index.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Rate/Entitlement.php, _underscore/Model/Compass/PurchaseOrder.php, _underscore/Model/Client/SalesOrder.php, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Elite/ServiceRequest.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/SalesOrderItem.php, _underscore/Model/Compass/ApprovalDecision.php, dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql, dbchanges2/Core/2026-08-06a - Service request and sales order payload interceptors.sql, dbchanges2/Client_Compass/2026-08-06 - RemoveBrokenSalesOrderItemPostPostInterceptor.sql, dbchanges2/Client_Compass/2026-08-14a - AddSalesOrderInactiveStandaloneItemPreInterceptors.sql, dbchanges2/Client_CompassCanada/2026-08-14a - AddSalesOrderInactiveStandaloneItemPreInterceptors.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/Rate/Entitlement.php, _underscore/Model/Compass/PurchaseOrder.php, _underscore/Model/Client/SalesOrder.php, _underscore/Model/Client/TransferOrder.php, _underscore/Model/Elite/SalesOrder.php, _underscore/Model/Elite/ServiceRequest.php, _underscore/Model/Compass/SalesOrder.php, _underscore/Model/Compass/SalesOrderItem.php, _underscore/Model/Compass/ApprovalDecision.php, dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql, dbchanges2/Core/2026-08-06a - Service request and sales order payload interceptors.sql, dbchanges2/Client_Compass/2026-08-06 - RemoveBrokenSalesOrderItemPostPostInterceptor.sql, dbchanges2/Client_Compass/2026-08-14a - AddSalesOrderInactiveStandaloneItemPreInterceptors.sql, dbchanges2/Client_CompassCanada/2026-08-14a - AddSalesOrderInactiveStandaloneItemPreInterceptors.sql, dbchanges2/Client_Nychh/2026-09-02a - TransferOrderNetsuitePushInterceptor.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 |
 | [cXML ShipNotice Gateway (ASN ingestion, carrier resolution, per-client provisioning)](features/cxml-shipnotice-gateway.md) | `_Component_Api_Cxml` accepts a supplier `ShipNoticeRequest` and translates it into a `POST /v2/advance-shipping-notices` on the V2 JSON engine. | api2/Component/Api/Cxml/Cxml.php, api2/Component/Api/V2/V2.php, api2/Controller/Index.php |
 | [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 |

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

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-20
+updated: 2026-09-02
 owners: ["mhammontree", "dfranks", "bala", "snaredla", "jcardinal"]
 files:
   - api2/Component/Api/V2/V2.php
@@ -15,6 +15,7 @@ files:
   - _underscore/Model/Rate/Entitlement.php
   - _underscore/Model/Compass/PurchaseOrder.php
   - _underscore/Model/Client/SalesOrder.php
+  - _underscore/Model/Client/TransferOrder.php
   - _underscore/Model/Elite/SalesOrder.php
   - _underscore/Model/Elite/ServiceRequest.php
   - _underscore/Model/Compass/SalesOrder.php
@@ -25,7 +26,9 @@ files:
   - dbchanges2/Client_Compass/2026-08-06 - RemoveBrokenSalesOrderItemPostPostInterceptor.sql
   - dbchanges2/Client_Compass/2026-08-14a - AddSalesOrderInactiveStandaloneItemPreInterceptors.sql
   - dbchanges2/Client_CompassCanada/2026-08-14a - AddSalesOrderInactiveStandaloneItemPreInterceptors.sql
+  - dbchanges2/Client_Nychh/2026-09-02a - TransferOrderNetsuitePushInterceptor.sql
 related:
+  - ../../worker2/features/netsuite-transferorder-outbound-push.md
   - ../../../clients/rate/features/aig-contract-creation.md
   - ./record-scripts.md
   - ../../toga2-commerce/features/inactive-item-purchase-gating.md
@@ -329,6 +332,34 @@ The corollary is that **reading the client subclass is not enough to know who a
 you must also read the parent chain *and* the interceptor rows of every tenant that overrides the
 same record.
 
+#### The deliberate exception — shared model + "the row is the switch" (2026-09-02)
+
+The rule above is about **accidental** reach. Putting a hook on `_Model_Client_X` **on purpose** is
+legitimate when the behaviour is generic and gated, and the interceptor row is the gate: *no row, no
+call.* Worked example — the transfer-order → NetSuite push lives on
+`_Model_Client_TransferOrder::postPost`, not on `_Model_Nychh_TransferOrder`, so *whoever has the
+`transfer-orders` row gets it* (see
+[Toga TransferOrder → NetSuite Push](../../worker2/features/netsuite-transferorder-outbound-push.md)).
+
+Three conditions make that safe, and all three must hold before you copy the pattern:
+
+1. **No client currently has a row for that record** — check every tenant, not just yours.
+2. **The behaviour is client-agnostic**, resolving everything from the record's own FKs.
+3. **You state the real prerequisite in the doc and the code.** Here the hook only works for a client
+   whose model uses `_Trait_Netsuite_TransferOrder` (that trait declares
+   `c_netsuiteInternalSalesOrderId`); NYCHH is the only one today, so **any other client given a
+   `transfer-orders` row would start pushing to NetSuite** and break on the missing field.
+
+**Adding an interceptor row for a shared-model hook is a code change, not configuration.**
+
+#### ⚠ Call `parent::postPost()` only if the parent actually declares it
+
+Elite's hook **must** call its parent; the transfer-order hook **must not**.
+`_Model_Client_TransferOrder` extends `_Model_True`, which declares **no `postPost`**, so
+`parent::postPost()` there is a fatal — the same *"Call to undefined method"* class of failure as a
+bad interceptor row, just from the other direction. **Read the parent chain up to `_Model_True`
+before adding the call by habit.**
+
 ### `Core.Records` facts for interceptor debugging
 
 - **`Core.Records.model` is UNIQUE** — exactly one record row per model class, so an interceptor's
@@ -595,6 +626,15 @@ and the failing environment**. It is a small table, and the drift is usually exa
 
 ## Change history
 
+- 2026-09-02 — Recorded the **deliberate shared-model exception**: a hook may live on
+  `_Model_Client_X` when the behaviour is client-agnostic and the interceptor row is the gate (no row,
+  no call), with the transfer-order → NetSuite push on `_Model_Client_TransferOrder::postPost` as the
+  worked example — plus the three conditions that must hold (no tenant already has a row for that
+  record, the logic resolves everything from the record's own FKs, and the real prerequisite is
+  stated: here the client's model must use `_Trait_Netsuite_TransferOrder`). Adding such a row is a
+  **code change, not configuration**. Also recorded the mirror-image fatal: **call
+  `parent::postPost()` only if the parent declares it** — `_Model_Client_TransferOrder` extends
+  `_Model_True`, which has none, so the parent call Elite's hook requires is a fatal there. (bala)
 - 2026-08-20 (later pass) — Recorded that **activating a client's FIRST interceptor row switches on
   the entire INHERITED chain**, with the Elite production outage as the worked example: two new
   `sales-orders` rows made every `POST /v2/sales-orders` return `EO-1` 500 with the order rolled

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

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-09-01
+updated: 2026-09-02
 owners: [tcox, bala, apeterson, jcardinal]
 files:
   - api2/Component/Api/V2/V2.php
@@ -154,6 +154,17 @@ GET /v2/transfer-orders/{uuid}/transfer-order-items
   alternative to the 1.0 direct-query fix (the developer applied both). **Ordering caveat:** the
   migration must run **after** the duplicate-`TransferOrderItems` cleanup, or the inline expansion
   returns all the dup rows.
+- **A BRIDGE table needs its own row too — and the header bridge is a different record from the item
+  bridge.** Reading a transfer order's **PO number** depends on
+  `transfer-orders (312) → purchase-orders-transfer-orders (325)`, the **header** bridge
+  (`_Model_Client_PurchaseOrders_TransferOrder`). Record **329**
+  (`purchase-order-items-transfer-order-items`) is the **item-level** bridge and is **not** what the
+  PO number reads through — production had 312→**329** and it had to be repointed to 325
+  (2026-09-02). Both rows are needed for the outbound transfer-order push, which reads lines *and*
+  PO number in one depth-4 call: see
+  [Toga TransferOrder → NetSuite Push](../../worker2/features/netsuite-transferorder-outbound-push.md).
+  Per-environment drift and repair order are in
+  [non-prod metadata drift](../../dbchanges2/workflows/nonprod-metadata-drift-repair.md).
 
 ### ⚠ `join` / `ojoin` drive the WHERE/filter — NOT the response shape
 
@@ -353,6 +364,12 @@ ACL gate for calculated fields lives at **:7216** in `getFullModelData()` — wh
   [V2 request logging](request-logging.md).
 
 ## Change history
+- 2026-09-02 — Recorded that a **bridge** collection needs its own `InherentRecordChildren` row and
+  that the **header** bridge is a different record from the item bridge: a transfer order's PO number
+  reads through `312 → 325 purchase-orders-transfer-orders`, **not** `329
+  purchase-order-items-transfer-order-items`; production carried 329 and was repointed to 325. Both
+  312→313 and 312→325 are prerequisites for the outbound transfer-order push's single depth-4 read.
+  (bala)
 - 2026-09-01 — **Recorded the biggest exception to this doc's own "always send an explicit `fields=`
   list" advice: an `_`-prefixed field named in `fields=` is NEVER ACL-checked.** `V2.php:3338`
   classifies a `FIELD_SQL` field as calculated *before* the ACL branch at `:3353`, and `:3353` then

package/knowledge/2.0/apps/dbchanges2/workflows/nonprod-metadata-drift-repair.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: workflow
 status: active
-updated: 2026-08-19
+updated: 2026-09-02
 owners: ["mhammontree", "bala", "kyalamarthi"]
 files:
   - dbchanges2/Core/2026-06-30a - ItemFulfillmentStageDefaultInterceptor.sql
@@ -23,6 +23,8 @@ related:
   - ../architecture.md
   - ./client-schema-drift-audit.md
   - ../../api2/features/api-payload-interceptors.md
+  - ../../api2/features/v2-rest-query-contract.md
+  - ../../worker2/features/netsuite-transferorder-outbound-push.md
   - ../../api2/workflows/environment-configuration-and-provisioning.md
   - ../../_underscore/features/acl-permission-chain.md
 ---
@@ -87,6 +89,42 @@ exercise TOGa Supply Fulfill & Ship (TRUE-80494).
 6. **Re-test the feature end-to-end in that environment**, then record what is still missing so the
    next person doesn't rediscover it.
 
+## `Core.InherentRecordChildren` drifts too — and MySQL **1452** means the `Records` row is missing
+
+`InherentRecordChildren` decides what a `/v2` read inlines (see
+[V2 REST query contract](../../api2/features/v2-rest-query-contract.md)), so it is exactly the kind
+of small metadata table that drifts per environment and produces "works in prod, empty in beta".
+
+Worked example (2026-09-02, `transfer-orders` = record **312**, needed by the outbound
+transfer-order push):
+
+| Environment | State found | Action |
+|---|---|---|
+| prod | 312→313 and 312→**329** (the *item*-level bridge) | repointed to 312→313 + 312→**325** |
+| client-sandbox | only 312→357 (`transfer-order-notes`) | added 313 and 325 |
+| dev-sandbox | **no rows for 312 at all** | still pending |
+
+> **⚠ `1452 Cannot add or update a child row: a foreign key constraint fails
+> (Core.InherentRecordChildren, CONSTRAINT fk_inherentrecordchildren_child FOREIGN KEY (recordId)
+> REFERENCES Records (id))` does NOT mean your bridge row is wrong — it means the `Core.Records` row
+> does not exist in THAT environment.** dev-sandbox has records 312 and 313 but **no record 325 at
+> all**. **Repair order is always `Records` → `RecordFields` → `InherentRecordChildren`.**
+
+**Copy the production literals** — `Core.Records` / `Core.RecordFields` ids are team-maintained
+platform constants, so the same numbers go in every environment (that is what lets a `Client/`
+migration hardcode a `recordFieldId`; see the architecture rule and the open question below):
+
+- **Record 325** — uuid `9b1c650c-f961-4718-bf29-c4ce4d54ae44`, `aclDatabase CLIENT`,
+  `childPolicy MATCH`, model `\_Model_Client_PurchaseOrders_TransferOrder`, route
+  `purchase-orders-transfer-orders`.
+- **Its four `RecordFields`**, all `isIdentifier = 1`: **2209** `id`
+  (`b2b498b2-c4a2-4ba9-8d18-aa967322dedd`), **2210** `uuid`
+  (`a9724441-9d3b-4a73-acd2-409f22ed2ce7`), **2211** `purchaseOrderId`
+  (`81aecb84-c4d6-4281-867d-ef915495b8aa`), **2212** `transferOrderId`
+  (`a4d5967d-dd7b-41d8-b42c-54f5cebe6647`). Ids 2209–2212 were verified **free** in dev-sandbox.
+- **Then** the two child rows: 312→313 and 312→325. Record **ACL** rows for 325 may also be needed —
+  untested; an `EZ-1` is the symptom.
+
 ## The `Client/` fan-out is skipped independently of `Core/` — and the gap is NON-CONTIGUOUS
 
 Measured on dev-sandbox 2026-08-17 (TRUE-80562): **31 of 33 tenant DBs lack
@@ -257,6 +295,14 @@ is caught up, test against a **local Forecast fixture** instead — see
 
 ## Change history
 
+- 2026-09-02 — Added `Core.InherentRecordChildren` as a drifting table, with record **312**
+  (`transfer-orders`) worked through all three environments: prod carried the **wrong** child (329,
+  the item-level bridge) and was repointed to **325**, client-sandbox had only 357 and got 313 + 325,
+  dev-sandbox still has none. Recorded the diagnostic that **MySQL 1452 on
+  `fk_inherentrecordchildren_child` means the `Core.Records` row is missing in that environment**
+  (dev-sandbox has no record 325 at all), that the repair order is **Records → RecordFields →
+  InherentRecordChildren**, and the prod literals to copy (record 325 + RecordFields 2209–2212, all
+  `isIdentifier = 1`, ids verified free in dev-sandbox). (bala)
 - 2026-08-19 — Recorded that the drift is **not only metadata**: dev-sandbox's `Forecast/` **DDL** fan-out
   appears unapplied since ~Feb 2026 — it has `Employees.departmentId` (2026-02) but is missing
   `Sales.amountDue` (2026-06-09), `Customers.accountType` (2026-07-14) and `Opportunities.clickupTaskId`

package/knowledge/2.0/apps/toga2-commerce/features/inactive-item-purchase-gating.md

@@ -6,7 +6,7 @@ project: TOGa Commerce
 client: shared
 type: feature
 status: active
-updated: 2026-08-14
+updated: 2026-09-02
 owners: ["bala"]
 files:
   - toga2-commerce/src/utils/checkIsItemPurchasable.ts
@@ -32,6 +32,7 @@ related:
   - ../../api2/features/v2-rest-query-contract.md
   - ../../../clients/compass-usa/profile.md
   - ../../../clients/compass-canada/profile.md
+  - ../../../clients/compass-usa/workflows/changing-a-kit-line-item.md
 ---
 
 ## Summary
@@ -53,6 +54,14 @@ dev-sandbox `Client_Compass`, across bundles that are themselves active:
 (32 inactive vs 3 active primaries). So a gate on the flag alone would break almost every kit on
 the storefront.
 
+**The tier is not a column on the item — it is the kit line's group.** A component's tier comes from
+`BundleItems.bundleItemGroupId` joined to `BundleItemGroups`, whose slugs are **1 `primary` /
+2 `secondary` / 3 `tertiary`** (same ids in `Client_Compass` and `Client_CompassCanada`, verified
+prod 2026-09-02). The "hero" of a kit is simply its `primary` line. **A kit can carry more than one
+*active* primary** — Compass bundles 27 and 140 each keep an old iPad hero (`MQ6J3LL/A-S`) alongside
+a new one (`MD7F4LL/A-S`) — so never assume one primary per bundle. See
+[Changing what is IN a Compass kit](../../../clients/compass-usa/workflows/changing-a-kit-line-item.md).
+
 **Therefore the gate is on the purchase CONTEXT, never on the flag alone.** The discriminator is
 whether the line belongs to a kit: `isset($payload->bundleItem)` server-side, the bundle wrapper
 client-side. Kit lines are never evaluated.
@@ -172,11 +181,24 @@ Implementation:
   had already opened an item kept seeing a working product page after it was switched off. That is
   why the item-detail queries are `staleTime: 0` + `gcTime: 0` **and** excluded from persistence.
   See [catalog cache freshness](./catalog-cache-freshness.md).
+- **⚠ Do not resolve a hero (or any kit line) by `partNumber` alone.** `Client_Compass.Items` can
+  hold the same part number twice with opposite flags — `MD7F4LL/A-S` is id **2760** (`title` set,
+  `isActive = 0`, the row the kits actually reference) and id **2784** (`title` NULL,
+  `isActive = 1`, unused). A part-number lookup can land on the twin that no kit uses, and the two
+  disagree about `isActive`. Match on `BundleItems.itemId`.
 - **The server check is one query per order, not per line** — uuids are deduped into a single
   `IN (…)` lookup, and the empty list returns early because `IN ()` is a MySQL syntax error.
 
 ## Change history
 
+- 2026-09-02 — Added how a component's **tier** is actually determined (`BundleItems.bundleItemGroupId`
+  to `BundleItemGroups`, slugs 1 `primary` / 2 `secondary` / 3 `tertiary` in both Compass schemas),
+  since the measured PRIMARY/secondary/tertiary table above never said where the tier comes from.
+  Recorded that a kit can hold **more than one active primary** (Compass bundles 27 and 140 keep
+  `MQ6J3LL/A-S` beside `MD7F4LL/A-S`), and added a gotcha that a hero must be resolved by
+  `BundleItems.itemId` rather than `partNumber` because `MD7F4LL/A-S` exists twice with **opposite**
+  `isActive` values (id 2760 used, `isActive = 0`; id 2784 unused, `isActive = 1`). Data findings from
+  a Compass kit data change; no code changed. (bala)
 - 2026-08-14 — TRUE-80489: built the layered gate stopping an `Items.isActive = 0` item being
   viewed, carted or ordered as a **standalone** line, with kit lines exempt. Recorded the measured
   reason the flag alone is unusable (84 of 85 active Compass bundles contain an inactive component;

package/knowledge/2.0/apps/toga25-supply/features/transfer-orders-page.md

@@ -6,8 +6,8 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-09-01
-owners: [apeterson]
+updated: 2026-09-02
+owners: [apeterson, bala]
 files:
   - toga25-supply/src/pages/TransferOrders/TransferOrders.tsx
   - toga25-supply/src/pages/TransferOrders/hooks/useTransferOrdersTableState.ts
@@ -49,6 +49,7 @@ related:
   - ../../toga-blox/features/api-client.md
   - ../../../../clients/nychh/profile.md
   - ../../../../clients/nychh/features/transfer-order-inventory-quantities.md
+  - ../../worker2/features/netsuite-transferorder-outbound-push.md
 ---
 
 ## Summary
@@ -412,6 +413,15 @@ visible in Core (neutral default; other tenants populate `TransferOrders.purchas
 - **Open dependency:** `Client/2026-08-28a` writes to `ThemeTokens`, a table created by
   `Client/2026-06-25a - SurfaceClientTables.sql`. Any prod tenant that never received `2026-06-25a`
   will error, and the full 36-tenant list was **not** audited.
+- **🚨 Two REQUIRED changes to the Create Transfer Order POST (2026-09-02), both for the new
+  NetSuite push.** The push is triggered from `_Model_Client_TransferOrder::postPost` — see
+  [Toga TransferOrder → NetSuite Push](../../worker2/features/netsuite-transferorder-outbound-push.md):
+  1. **Drop `"number"` from the POST body.** The modal currently sends e.g.
+     `"number": "286906"`, and `FIELD_AUTOINCREMENT` only generates the new `TA100000` sequence when
+     `number` arrives **NULL** — a supplied value silently wins, with no error.
+  2. **Send `transferOrderItems` NESTED in the same POST.** `postPost` reads the order back
+     in-request; if the lines are posted in separate calls afterwards it sees **zero lines** and the
+     push aborts (and the trigger would have to move).
 - ~~No `transfer-orders-list-actions` BUTTON_BAR surface~~ — **closed** by `Core/2026-08-28b`
   (Surface 52, elements 187–189); the header is now `SurfaceActionBar`-driven like Sales Orders.
 - **Test data lives in the session scratchpad, never in dbchanges2** (24 seed orders + an unseed
@@ -479,6 +489,12 @@ deliberate, separate exception — see [surface-frontend](./surface-frontend.md)
   earlier migration without names, so a name-based lookup on them finds nothing.
 
 ## Change history
+- 2026-09-02 — Recorded two **required** changes to the Create Transfer Order POST, both driven by
+  the new [TransferOrder → NetSuite push](../../worker2/features/netsuite-transferorder-outbound-push.md):
+  **drop `"number"`** (the new `TA100000` `FIELD_AUTOINCREMENT` sequence only generates when `number`
+  arrives NULL — a supplied value silently wins) and **send `transferOrderItems` nested in the same
+  POST** (the `postPost` hook reads the order back in-request; lines posted separately mean it sees
+  zero lines and the push aborts). (bala)
 - 2026-09-01 — **Rebuilt the Create Transfer Order modal against the live Claude Design export and
   closed two of its three data-layer blockers.** The **single-source lock is superseded**: Source
   Location is now the one active `allowSending = 1` location, read-only from open and never derived

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

@@ -33,6 +33,7 @@
 | [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 Backfill Worker (bulk reconciliation recipe)](features/netsuite-supporting-record-backfill-worker.md) | The **bulk counterpart** to the [supporting-record webhook importer](./netsuite-supporting-record-webhook-importer.md). | worker2/Worker/Netsuite/CustomerAccountTypeBackfill.php, worker2/Worker/Netsuite/ItemFulfillableBackfill.php, worker2/Worker/Netsuite/OpportunityEndCustomerBackfill.php, worker2/Worker/Netsuite/Customer.php, library/app/model/forecast2/customer.php, worker/crons/toga2/forecast2/common_import_sales_from_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, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, worker/crons/toga2/forecast2/import_supporting_records.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php, worker2/Worker/Netsuite/CustomerAccountTypeBackfill.php, library/app/api/netsuite/rest.php, library/app/model/forecast2/customer.php |
+| [Toga TransferOrder → NetSuite Push (a $0 sales order IS the transfer order)](features/netsuite-transferorder-outbound-push.md) | A transfer order created in TOGa Supply is pushed to NetSuite as a **zero-value sales order**. | worker2/Worker/Netsuite/SalesOrder.php, _underscore/Model/Client/TransferOrder.php, dbchanges2/Client_Nychh/2026-09-02a - TransferOrderNetsuitePushInterceptor.sql, test/@Bala/tests/netsuite_transferorder_payload_tests.php, test/@Bala/tests/transferorder_interceptor_tests.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 |
 | [NYCHH Asset-Tag Backfill (worker2)](features/nychh-asset-tag-backfill.md) | Keeps NYC Health & Hospitals (`Client_Nychh`) unit asset tags and MAC addresses synced from NetSuite. | worker2/Worker/Client/Nychh.php, worker2/Worker/Client/Nychh/AssetTagBackfill.php, worker/crons/toga2/netsuite/verify_fulfillment_asset_tag_sync_nychh.php, worker/crons/toga2/netsuite/backfill_all_asset_tags_from_netsuite_nychh.php |

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-20
+updated: 2026-09-02
 owners: ["bala"]
 files:
   - worker2/Worker/Netsuite/SalesOrder.php
@@ -14,6 +14,7 @@ files:
   - worker/crons/toga2/prudential/transmissions_to_netsuite.php
 related:
   - ./netsuite-salesorder-open-orders-sync.md
+  - ./netsuite-transferorder-outbound-push.md
   - ./creating-worker-actions.md
   - ../../_underscore/features/netsuite-rest-client.md
   - ../../api2/features/api-payload-interceptors.md
@@ -37,6 +38,24 @@ share no code, constants or helpers (verified 2026-08-10: the inbound half's 2,2
 tokens are identical to `origin/_production`). **Edit one without assuming anything about the
 other.**
 
+**Since 2026-09-02 this same outbound half also pushes TRANSFER orders** (as $0 NetSuite sales
+orders) through a separate entry point that reuses `buildNetSuiteOrder`, `doCreate`, the
+`externalId` machinery and `writeBackNetSuiteId`. That route is its own subject — see
+[Toga TransferOrder → NetSuite Push](./netsuite-transferorder-outbound-push.md) — and everything
+below still describes the **sales-order** path only.
+
+### The shared builder now serves two order types — the changes were additive and defaulted
+
+Four helpers gained a transfer-order branch, each **defaulting to the old behaviour**:
+`buildExternalId($uuid, $isTransferOrder = false)`,
+`fetchSalesOrder($ctx, $uuid, $isTransferOrder = false)`, `writeBackNetSuiteId()` (route), and
+`buildNetSuiteOrder()`, which now prefers an explicit `$order->otherRefNum` **before** the
+ticket-number → service-request-number chain. **`CreateNetSuite` / `UpdateNetSuite` / `Sync` keep
+their original signatures**, and the sales-order path is provably unchanged because
+`_Model_Client_SalesOrder` declares **no `otherRefNum` field** — the new branch is unreachable from
+a sales order. When you add a precedence like that, verify the *other* model does not have the field
+rather than assuming it will not be set.
+
 ## Key files / entry points
 
 | Action | Method | Purpose |
@@ -201,7 +220,7 @@ cleanup caveat is in the Elite doc; the general rule is in
   `CreateNetSuite`/`UpdateNetSuite` as thin wrappers — which also closed a TOCTOU, since the decision
   and the write now use the same fetched record.
 
-## Test harness (85 tests, all passing)
+## Test harness (85 tests — 84 pass, test 9 fails BY DESIGN)
 
 `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
@@ -222,6 +241,20 @@ run, create, update, and the job-carried-snapshot path, plus:
 Stub additions this needed: `$throwOnCreate` and `$createPayloadsSeen` on the NetSuite stub, and a
 `$nextRows` queue on the `_Query` stub so `getClientContext()` resolves.
 
+### ⚠ Test 9 is a PRE-EXISTING failure — do not attribute it to whatever you are working on
+
+The suite reports **84 passed / 1 failed**. Test 9 asserts `otherRefNum` is the order number
+(`SA100001`), from when that field was sourced from `SalesOrders.number`; the shipped code sources it
+from the ticket number and then the service-request number. It is **left failing on purpose** — a
+failing test is information, and "fixing" it would mean changing the Elite path, which the developer
+ruled out.
+
+**Technique worth keeping: to prove a test failure pre-dates your change, run the harness against a
+`git show HEAD:<path>` copy** in a scratch directory (`git show HEAD:Worker/Netsuite/SalesOrder.php`
+→ scratch file) — the harness hardcodes an absolute `require` path, so pointing it at the committed
+copy is the cheap way to get a baseline. Done 2026-09-02: identical **84/1**, so the failure predates
+the transfer-order work.
+
 ## Gotchas / known issues
 
 - **⚠ A crash *after* the NetSuite create leaves an orphan.** `createRecord()` reads the `Location`
@@ -265,6 +298,17 @@ Stub additions this needed: `$throwOnCreate` and `$createPayloadsSeen` on the Ne
 
 ## Change history
 
+- 2026-09-02 — This outbound half now also serves **transfer orders** (a $0 NetSuite sales order)
+  through a separate entry point — see
+  [Toga TransferOrder → NetSuite Push](./netsuite-transferorder-outbound-push.md). Four shared
+  helpers gained additive, defaulted transfer-order branches (`buildExternalId`, `fetchSalesOrder`,
+  `writeBackNetSuiteId` route, and an `$order->otherRefNum` precedence in `buildNetSuiteOrder`);
+  `CreateNetSuite` / `UpdateNetSuite` / `Sync` signatures are untouched and the sales-order path is
+  provably unchanged because `_Model_Client_SalesOrder` has no `otherRefNum` field. Also recorded
+  that harness **test 9 is a pre-existing failure** (asserts the old `otherRefNum = SalesOrders.number`
+  sourcing) — left failing deliberately — and the technique that proved it: run the harness against a
+  `git show HEAD:` copy of the worker for a baseline. (bala)
+
 - 2026-08-20 — **Made the create idempotent with a NetSuite `externalId`**
   (`NETSUITE_EXTERNAL_ID_PREFIX = 'toga-so-'`, `buildExternalId()`,
   `findNetSuiteOrderByExternalId()`, and `writeBackNetSuiteId()` extracted because three paths now