toga-ai 1.0.671 → 1.0.673

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

@@ -92,6 +92,20 @@ Forecast2 tables already store.
 - **TO_DATE rejects impossible dates** (e.g. `2026-06-31`) with an opaque HTTP 400 — validate
   calendar dates before building SuiteQL.
 
+- **The line SuiteQL must SELECT the line location or it is always NULL — the shim reads it but
+  didn't select it.** `listSalesOrders()`'s line query now selects `tl.location` and
+  `BUILTIN.DF(tl.location) AS location_name`. The line-shim assembly code already *read* those two
+  fields, but the SELECT never included them, so every line's location came back null — which broke
+  NYCHH transfer-order origin resolution (`TransferOrders.originLocationId` is NOT NULL → V2 `EV-10`).
+  Same class of bug as ShipItem cost above: a field the shim consumes must actually be in the SELECT.
+  (Added 2026-08-27.)
+
+- **Custom body fields ride in `customFieldList` on the per-id REST GET.** `fetchSalesOrderById()`
+  now carries `custbody_stocking_order` (NetSuite internal id 7097) via `customFieldList` so the
+  importer can route NYCHH orders (checked = stocking/in → SalesOrders, unchecked = transfer/out →
+  TransferOrders). A custom field absent from the record reads as null downstream. See
+  [NYCHH NetSuite → TransferOrders import](../../../clients/nychh/features/netsuite-transfer-order-import.md).
+
 ## Transaction status sourcing (1.0) — and the 2026.2 REST `status.id` change
 
 1.0 reaches NetSuite over **two transports, and neither reads status off a REST record GET
@@ -136,9 +150,21 @@ None — uniform across clients (NetSuite is a single shared account).
   `??=`, or `match`. Lint with `C:\xampp7\php\php.exe -l` before deploying.
 - Field availability varies by NetSuite account **and** record type — probe the live account
   before assuming a column/relationship exists.
+- **`App_NetSuite::getCustomFieldValue()` (`library/app/netsuite.php`) must be warning-safe.** 1.0
+  runs on PHP 7.2 in an unguarded path, so any PHP warning → `exit()` (kills the cron). It was
+  hardened 2026-08-27 with `?? []` / `?? null` guards on the custom-field-list traversal. Keep that
+  discipline when touching it.
 
 ## Change history
 
+- 2026-08-27 — Recorded three field-semantics facts from NYCHH transfer-order support:
+  `listSalesOrders()` line SuiteQL now **selects `tl.location` + `BUILTIN.DF(tl.location)`** (the line
+  shim read them but never selected them → always null, breaking TO origin resolution / V2 `EV-10`);
+  `fetchSalesOrderById()` now carries **`custbody_stocking_order` (id 7097)** via `customFieldList` for
+  order routing; and `App_NetSuite::getCustomFieldValue()` was hardened with `?? []`/`?? null` for
+  PHP 7.2 warning-safety. See
+  [NYCHH NetSuite → TransferOrders import](../../../clients/nychh/features/netsuite-transfer-order-import.md).
+  (jcardinal)
 - 2026-08-25 — Documented **1.0 transaction-status sourcing across both transports** and the
   conclusion that the **NetSuite 2026.2 REST `status.id` text→letter standardization does not
   affect 1.0** (SuiteAnswers 89313). `App_Api_Netsuite_Rest` derives status from the SuiteQL

package/knowledge/1.0/apps/library/features/toga2-api-client-and-bridge.md

@@ -396,6 +396,17 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
 
 ## Change history
 
+- 2026-08-27 — `send()`'s throw sites were **reverted to plain `throw new Exception(...)`** (both
+  sites) as part of removing the sync engine's swallow-and-skip data-loss bug — the importer must
+  propagate a failed write, not catch it (see
+  [NetSuite → TOGa Supply per-client sync](../../worker/features/netsuite-togasupply-per-client-sync.md),
+  2026-08-27). New transfer-order importer methods landed in this class for NYCHH:
+  `isTransferOrder()` rewritten + private `isStockingOrder()` (route by NetSuite
+  `custbody_stocking_order`), private `linkPurchaseOrderToTransferOrder()`, TO origin resolution in
+  `syncSalesOrderFromNetsuite`, `transferOrderItem.uuid` linking in `syncItemFulfillmentFromNetsuite`,
+  and an expanded `syncTransferOrderFromNetsuite` status map — all documented on
+  [NYCHH NetSuite → TransferOrders import](../../../clients/nychh/features/netsuite-transfer-order-import.md).
+  (jcardinal)
 - 2026-08-17 — Recorded that **depth-4 `GET /sales-orders` omits the `itemFulfillmentItems` and
   `invoiceItems` reverse-hasMany collections** (it does return `salesOrderItems` and the PO-link
   bridges), verified against prod `Logs_Compass.Api` — so code guarding on those collections from

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

@@ -120,6 +120,39 @@ client's `Parameters` table back before the lost window. Re-import is **idempote
 on `c_netsuiteInternal*Id` and `SalesOrders.c_netsuiteInternalSalesOrderId` carries a unique index —
 so a rewind re-PUTs what is already there and POSTs only what is missing.
 
+### ⚠ 2026-08-27: all per-order `try/catch` REMOVED — every section now fails LOUD (was a data-loss bug)
+
+The "section-specific isolation" described just above was a **transient, harmful state** and no
+longer exists. On 2026-08-20 a prior dev (Rohan) had wrapped **each order dispatch** in all six
+sections in `try { … } catch (Throwable) { error_log }`, and each section in `try { … } finally {
+finishModeIteration }`. The effect was a **silent data-loss bug**: any non-2XX write was swallowed,
+the record was dropped, **the watermark/checkpoint still advanced past it** (permanent loss), and the
+execution mode was reset to **IDLE** on failure — so the next run had no idea the prior run had
+failed.
+
+**Decision + fix (this session), the standing behavior now:**
+
+- **All 6 per-order `catch (Throwable)` skips removed** (SALES_ORDERS, PURCHASE_ORDERS, INVOICES,
+  ITEM_RECEIPTS, ITEM_FULFILLMENTS, INVENTORY_ADJUSTMENTS). A failed dispatch now **propagates**.
+- **All 6 section-level `try/finally` removed.** `finishModeIteration()` now runs on the **success
+  path only**. On failure the cron **aborts**, the watermark PUT is **skipped**, and the execution
+  mode is **left as RUNNING** so the next run knows the prior run failed (and the ÷3 window shrink
+  fires, as intended).
+- `startModeIteration`'s internal try/catch is **kept** (it re-throws, does not skip).
+- The `send()` throw sites in `library/app/api/toga2.php` were reverted to plain
+  `throw new Exception(...)`.
+
+**REJECTED alternative (do not re-attempt):** converting the throws into a custom
+`App_Exception_ApiResponse` and catching *that*. The real fix is to **stop catching `Throwable`**, not
+to introduce a catchable wrapper — the `app/exception/apiresponse.php` class created for that approach
+was deleted.
+
+**Net:** a failed import halts loudly and preserves `RUNNING` state instead of advancing past dropped
+records. The isolation discussion above now applies uniformly — **no** section steps over a bad
+record; every section behaves the way SALES_ORDERS always did (throw → freeze at RUNNING → same
+poison record re-tried each run → go read the error). This is an application of the universal
+coding-style rule *never catch-and-silently-ignore*, not a new engine-specific policy.
+
 ### Sections are NOT order-dependent — one cursor can be rewound alone
 
 Each section's `startModeIteration()` reads only **its own** `Parameters` key, and the PO section
@@ -273,6 +306,14 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
 
 ## Client variations
 
+- **Transfer-order routing is opt-in per wrapper (default OFF).** A client whose NetSuite
+  *transfer orders* arrive as NetSuite *sales orders* can have the importer split them into
+  `TransferOrders` vs `SalesOrders` by setting
+  `const IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING = true;` before the `require_once`
+  (NYCHH's `sync_togasupply_hh.php` is the only one that does). The signal is the NetSuite custom
+  checkbox `custbody_stocking_order`, read by `App_Api_Toga2::isTransferOrder()`/`isStockingOrder()`
+  — **not** a dollar/hold heuristic. Full mechanics, PO bridges, and origin-location resolution:
+  [NYCHH NetSuite → TransferOrders import](../../../clients/nychh/features/netsuite-transfer-order-import.md).
 - `isParentCustomer` — `true` walks NetSuite child customers (`listChildCustomers`); `false`
   syncs the single customer. Prudential-EDI and the live Quad wrapper use `false`.
 - The original combined-array entries used `App_Api_Toga2::CLIENT_UUID_*` consts for Quad and
@@ -465,6 +506,18 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
 
 ## Change history
 
+- 2026-08-27 — **Removed a silent data-loss bug: all per-order `catch (Throwable)` skips and all
+  section-level `try/finally` were deleted, so every section now fails LOUD.** A 2026-08-20 change had
+  wrapped each order dispatch in `catch (Throwable) { error_log }` and each section in
+  `try/finally { finishModeIteration }` — swallowing any non-2XX write, dropping the record, advancing
+  the watermark past it, and resetting mode to IDLE. Now dispatch propagates, `finishModeIteration()`
+  runs on the success path only, and a failure aborts with the watermark skipped and mode left
+  RUNNING; `send()`'s throw sites in `library/app/api/toga2.php` reverted to plain `throw`. The
+  rejected `App_Exception_ApiResponse` wrapper was deleted. The "isolation is section-specific" gotcha
+  now applies uniformly — no section steps over a bad record. Also recorded the new opt-in
+  transfer-order routing switch (`IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING`, default off,
+  NYCHH only) — see [NYCHH NetSuite → TransferOrders import](../../../clients/nychh/features/netsuite-transfer-order-import.md).
+  (jcardinal)
 - 2026-08-26 — Corrected the IF full-reconcile tracking claim and **fixed two bugs** in
   `syncItemFulfillmentFromNetsuite`'s single-tracking-number branch: **318 (item) was never written**
   (`Client_Quad` had 0 rows → blank Tracking # column) and **319 (unit) received only the last

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

@@ -222,6 +222,32 @@ then checks the caller's roles against `AclRecordPermissions` (→ `EZ-1` if no
 readable/writable fields from `AclFieldPermissions`. `_Model_Core_Page::meta()` reads the same
 tables to return per-page ACL to the frontend.
 
+> **⚠ There is NO ACL/metadata caching layer — the load is per-request and there is nothing to bust.**
+> `buildLookups()` re-reads the ACL/metadata tables on **every** request, so an inserted/updated
+> `AclCustomFieldPermissions` / `CustomRecordFields` / `AclFieldPermissions` row takes effect on the
+> **very next request**. There is no cache-invalidation step, and looking for one is a dead end
+> (verified 2026-08-27 wiring NYCHH transfer-order custom fields — a whole debugging pass was wasted
+> on the assumption that a cache had to be cleared). If a freshly-applied grant/metadata row still
+> doesn't take, suspect the row itself (wrong DB/role/id, or a broken cross-schema subselect that
+> inserted zero rows), not staleness.
+
+### ⚠ A nested FK resolved BY a custom field needs `CustomRecordFields.isIdentifier = 1`
+
+When the API resolves a nested foreign-key reference **through a custom (`c_`) field** — i.e. the
+custom field is the identifier the child is matched on — that field's `CustomRecordFields.isIdentifier`
+must be `1`, or the write fails **`EV-12`** with `searchableIdentifierFields:[id]` (the resolver falls
+back to `id` because no custom field is marked searchable). This is a **fourth** thing to check beyond
+column + `CustomRecordFields` row + `AclCustomFieldPermissions` grant + model declaration. Verified
+2026-08-27 on NYCHH `c_netsuiteInternalTransferOrderStatus` (recordId 351): the field existed and was
+granted, but the nested transfer-order-stage lookup 400'd until `isIdentifier` was set to 1.
+
+**The `c_` declaration on a client-override model comes from its NetSuite trait.** The pattern for a
+NetSuite-synced record is `_Model_<Client>_X extends _Model_Client_X { use _Trait_Netsuite_X; }` — the
+trait is what declares the `c_` fields (so a client with only `extends`, no `use`, is missing them and
+its POST 500s `EO-1`). NYCHH's `_Model_Nychh_TransferOrder` / `_Model_Nychh_TransferOrderStage` had to
+be **created** for this reason before their transfer orders could carry NetSuite ids — see
+[NYCHH transfer-order inventory & quantities](../../../clients/nychh/features/transfer-order-inventory-quantities.md).
+
 ## Navigation / action flags (`Core.AclActions` + `AclActionPermissions`) — a THIRD gate
 
 A UI control that is not a record CRUD operation and not a scripted API — a nav item, an "Add" or
@@ -410,6 +436,15 @@ hardcoded `Core.RecordFields` id literals instead of a subselect.
       and every repo is on the **same branch** so the generated model matches the DB.
 
 ## Change history
+- 2026-08-27 — Recorded two facts from wiring NYCHH transfer-order custom fields: **there is NO
+  ACL/metadata cache** (`buildLookups()` re-reads per request, so a new grant/metadata row applies on
+  the next request — no cache-bust exists; a whole debugging pass was wasted assuming one did), and a
+  **nested FK resolved by a custom field needs `CustomRecordFields.isIdentifier = 1`** or the write
+  400s `EV-12 searchableIdentifierFields:[id]` (NYCHH `c_netsuiteInternalTransferOrderStatus`, recordId
+  351). Also noted that a client-override model's `c_` declarations come from its `_Trait_Netsuite_X`
+  (create `_Model_<Client>_X { use _Trait_Netsuite_X; }` or the POST 500s `EO-1`). See
+  [NYCHH transfer-order inventory & quantities](../../../clients/nychh/features/transfer-order-inventory-quantities.md).
+  (jcardinal)
 - 2026-08-26 - Added the **verify-per-sibling-field, verify-as-the-least-privileged-role** rule:
   columns of the same table often carry different role sets, so adding one more field to a `fields=`
   list is a permission change. `Client_Quad.Currencies` grants `code` (1424) and `symbol` (1425) to

package/knowledge/2.0/apps/api2/features/v2-api-error-codes.md

@@ -55,6 +55,8 @@ migration instead of re-deriving it. All field/script ACL rows live in the **CLI
 | **EV-5** | Duplicate `transactionId` | The globally-unique `transactionId` was reused | Send a fresh unique `transactionId` per request |
 | **EV-13** | Validation — page size too large | `recordsPerPage` exceeds the **10000** max | Lower `recordsPerPage` and paginate with `page` |
 | **EV-12** | Record's parent not synced | (Fulfill & Ship) POST `/item-fulfillments` when the Sales Order isn't synced into Toga yet | `GET /sales-orders/syncNetsuiteSalesOrder?netsuiteInternalSalesOrderId=<id>` first |
+| **EV-12** | `invalidSearchableField` / `searchableIdentifierFields:[id]` on a nested write | A nested FK is being resolved **through a custom (`c_`) field**, but that field is not marked searchable, so the resolver has only `id` | Set **`CustomRecordFields.isIdentifier = 1`** on that `c_` field (NYCHH `c_netsuiteInternalTransferOrderStatus`, recordId 351). Also confirm the field is declared on the client model via its `_Trait_Netsuite_*` — see the [ACL chain](../../_underscore/features/acl-permission-chain.md) |
+| **EV-10** | NOT NULL column received NULL on insert (e.g. `originLocationId cannot be null`) | Either the payload never resolved a value for a NOT NULL column, **or** a NOT NULL column that is **not a writable V2 field** was expected to arrive in the payload | Resolve the value upstream (NYCHH `TransferOrders.originLocationId`: select `tl.location` in the SuiteQL + fall back to the first line's location), **or** default the column in the ORM if it is server-owned — see EV-8 below and diagnosis note 15 |
 
 ## How to diagnose
 
@@ -197,6 +199,15 @@ migration instead of re-deriving it. All field/script ACL rows live in the **CLI
     not on matching the response text — see
     [V2 deadlock-retry](./v2-deadlock-retry.md).
 
+15. **A NOT NULL column that is NOT a writable V2 field must be DEFAULTED in the ORM — never sent in
+    the payload.** Adding the key to the POST body throws **`EV-8`** ("field does not exist") because
+    the column has no writable-field registration; but leaving it out throws the DB NOT NULL error on
+    insert. The fix is neither — declare a model default so the ORM writes it without a payload key,
+    e.g. `public $isActive = [self::FIELD_BOOLEAN, self::FIELDOPT_DEFAULT => true];` on
+    `_Model_Client_TransferOrder` (2026-08-27, NYCHH transfer-order POST). Contrast with a NOT NULL
+    column that *should* come from the caller/upstream (that is `EV-10` — resolve the value, don't
+    default it).
+
 ## BREAKING (2026-07-30): `error` is now an object, not a bare string
 
 The V2 envelope's `error` changed from a bare string (`"EO-1"`) to an **object**:
@@ -281,6 +292,12 @@ Full mechanics:
 - The response-envelope shape and code families: see [api2 architecture](../architecture.md).
 
 ## Change history
+- 2026-08-27 — Added three codes/notes from the NYCHH transfer-order POST work: **EV-10** (a NOT NULL
+  column received NULL — `originLocationId cannot be null`; resolve upstream or default in the ORM), a
+  second **EV-12** flavor (`searchableIdentifierFields:[id]` — a nested FK resolved *through* a `c_`
+  field needs `CustomRecordFields.isIdentifier = 1`), and **diagnosis note 15**: a NOT NULL column
+  that is **not a writable V2 field** must be defaulted in the ORM (`FIELDOPT_DEFAULT`), never sent in
+  the payload — sending it is `EV-8`, omitting it is a DB NOT NULL error. (jcardinal)
 - 2026-08-25 — Added the diagnostic that a **malformed bearer token returns EO-1 500 instead of
   EN-3 401**: the header/payload `json_decode` yields `null` and `property_exists()` throws a
   `TypeError` (`V2.php` ~1840); the sibling check at ~826 already guarded with `is_object()`.

package/knowledge/2.0/apps/saml/architecture.md

@@ -6,7 +6,7 @@ project: SAML SSO Gateway
 client: shared
 type: architecture
 status: active
-updated: 2026-06-11
+updated: 2026-08-27
 owners: ["rgirish", "jcardinal"]
 files:
   - saml/index.php
@@ -71,6 +71,14 @@ To onboard a new SSO client, add the class in `_underscore` — not in this repo
 - **`_underscore` pulled at deploy time** via `.ebextensions/git.php` + prebuild hook — clones branch `_production`. Deploy `saml` after `_underscore` merges to pick up framework changes.
 - **CodePipeline:** Source (GitHub `_production`) → ManualApproval → Deploy (EB).
 - **Composer deps** installed at postdeploy via `015_install_composer.sh`.
+- **Non-prod shared-ALB self-registration (2026-08-27).** Postdeploy hook
+  `060_register_instance_to_shared_application_load_balancer.sh` + `ebs/register_instance_to_shared_application_load_balancer.php`
+  register a non-production `saml` instance into the target group named exactly its EB env name;
+  **skips `production`** (so `saml-production` is unaffected) and always `exit 0`. Requires
+  `aws/aws-sdk-php` (now in `composer.json`, lock/vendor to be regenerated) and two IAM actions on
+  the instance profile (`elasticloadbalancing:DescribeTargetGroups` region-scoped +
+  `RegisterTargets` scoped to the non-prod target-group ARN). See
+  [ALB target-group auto-registration](../worker2/features/alb-target-group-auto-registration.md).
 
 ## Dependencies
 
@@ -88,3 +96,4 @@ To onboard a new SSO client, add the class in `_underscore` — not in this repo
 ## Change history
 - 2026-06-11 — Added `transactionCommit()` before redirect; wrapped `getAuthenticatedSsoUser()` in try/catch with Sentry; echo+exit on auth failure (rgirish)
 - 2026-06-25 — Sharpened signature-verification gotcha with explicit threat model and flagged it as the repo's top security priority; documented plaintext secrets in `production.ini` + hardcoded Sentry DSN in `Controller/Index.php` with SSM Parameter Store recommendation (jcardinal)
+- 2026-08-27 — Documented non-prod shared-ALB self-registration postdeploy hook (`060_...sh` + `ebs/register_instance_to_shared_application_load_balancer.php`); skips `production`, requires `aws/aws-sdk-php` + two IAM actions; cross-linked worker2 ALB auto-registration feature (jcardinal)

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

@@ -3,7 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Worker (worker2) Architecture](architecture.md) | Worker (repo `worker2`) is an AWS Elastic Beanstalk **Worker Tier** application that processes background jobs. | worker2/Controller/Index.php, worker2/Worker/, worker2/LambdaFunctions/, _underscore/Worker.php, worker2/composer.json |
-| [Deploy-Time Auto-Registration to the Shared ALB Target Group (non-production)](features/alb-target-group-auto-registration.md) | TOGA does **not** pay for EB-managed load-balancer registration, so an EB instance is normally **not** added to its environment's ALB target group — a fresh or | worker2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, worker2/ebs/register_instance_to_shared_application_load_balancer.php, worker2/.platform/hooks/prebuild/_shared/040-write-instance-id.sh, worker2/.platform/hooks/prebuild/_shared/041-write-region.sh, worker2/.platform/hooks/prebuild/_shared/042-write-eb-environment.sh, api2/.platform/hooks/prebuild/_shared/042-write-eb-environment.sh, worker2/.platform/hooks/postdeploy/015_install_composer.sh, api2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, api2/ebs/register_instance_to_shared_application_load_balancer.php |
+| [Deploy-Time Auto-Registration to the Shared ALB Target Group (non-production)](features/alb-target-group-auto-registration.md) | TOGA does **not** pay for EB-managed load-balancer registration, so an EB instance is normally **not** added to its environment's ALB target group — a fresh or | worker2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, worker2/ebs/register_instance_to_shared_application_load_balancer.php, worker2/.platform/hooks/_shared/040-write-instance-id.sh, worker2/.platform/hooks/_shared/041-write-region.sh, worker2/.platform/hooks/_shared/042-write-eb-environment.sh, worker2/.platform/hooks/postdeploy/015_install_composer.sh, saml/.platform/hooks/_shared/040-write-instance-id.sh, saml/.platform/hooks/_shared/041-write-region.sh, saml/.platform/hooks/_shared/042-write-eb-environment.sh, saml/.platform/hooks/prestart/040-write-instance-id.sh, saml/.platform/hooks/prestart/041-write-region.sh, saml/.platform/hooks/postdeploy/040-write-instance-id.sh, saml/.platform/hooks/postdeploy/041-write-region.sh, saml/.platform/hooks/postdeploy/042-write-eb-environment.sh, saml/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, saml/ebs/register_instance_to_shared_application_load_balancer.php, saml/composer.json, api2/.platform/hooks/prebuild/_shared/042-write-eb-environment.sh, api2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh, api2/ebs/register_instance_to_shared_application_load_balancer.php |
 | [All-Client Email Queue Monitor (Monitor/Operations/EmailQueue)](features/all-client-email-queue-monitor.md) | `_Worker_Monitor_Operations::EmailQueue()` is the cross-client health check for the 2.0 outbound email queue (`Logs_<Client>.Email` — see [2.0 Email Send Pipeli | worker2/Worker/Monitor/Operations.php, _underscore/Database.php, _underscore/Query.php, dbchanges2/Logs_Client/2026-05-21 - Email.sql |
 | [Automated PR Merger — Concurrent Force-Push Clobber Race](features/automated-pr-merger-force-push-race.md) | The automated PR merger `_Worker_Team_GitHub::Merge` (`worker2` `Worker/Team/Github.php`) merges approved PRs to `_production` by **force-pushing from a clone t | Worker/Team/Github.php |
 | [Callback Scheduling ("call me back") — worker2 AI-BDR](features/callback-scheduling.md) | The **AI-BDR callback path**: what happens between a prospect saying *"call me back later"* on a Vapi call and the dialer actually placing that second call. | worker2/Worker/Vapi.php, worker2/Worker/Ai/Bdr/Vapi.php, worker2/Controller/Index.php |

package/knowledge/2.0/apps/worker2/features/alb-target-group-auto-registration.md

@@ -6,20 +6,32 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-08-04
+updated: 2026-08-27
 owners: [jcardinal]
 files:
   - worker2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh
   - worker2/ebs/register_instance_to_shared_application_load_balancer.php
-  - worker2/.platform/hooks/prebuild/_shared/040-write-instance-id.sh
-  - worker2/.platform/hooks/prebuild/_shared/041-write-region.sh
-  - worker2/.platform/hooks/prebuild/_shared/042-write-eb-environment.sh
-  - api2/.platform/hooks/prebuild/_shared/042-write-eb-environment.sh
+  - worker2/.platform/hooks/_shared/040-write-instance-id.sh
+  - worker2/.platform/hooks/_shared/041-write-region.sh
+  - worker2/.platform/hooks/_shared/042-write-eb-environment.sh
   - worker2/.platform/hooks/postdeploy/015_install_composer.sh
+  - saml/.platform/hooks/_shared/040-write-instance-id.sh
+  - saml/.platform/hooks/_shared/041-write-region.sh
+  - saml/.platform/hooks/_shared/042-write-eb-environment.sh
+  - saml/.platform/hooks/prestart/040-write-instance-id.sh
+  - saml/.platform/hooks/prestart/041-write-region.sh
+  - saml/.platform/hooks/postdeploy/040-write-instance-id.sh
+  - saml/.platform/hooks/postdeploy/041-write-region.sh
+  - saml/.platform/hooks/postdeploy/042-write-eb-environment.sh
+  - saml/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh
+  - saml/ebs/register_instance_to_shared_application_load_balancer.php
+  - saml/composer.json
+  - api2/.platform/hooks/prebuild/_shared/042-write-eb-environment.sh
   - api2/.platform/hooks/postdeploy/060_register_instance_to_shared_application_load_balancer.sh
   - api2/ebs/register_instance_to_shared_application_load_balancer.php
 related:
   - ../architecture.md
+  - ../../saml/architecture.md
   - ../../api2/workflows/codepipeline-codeconnections-deploy.md
   - ../../api2/architecture.md
 ---
@@ -34,8 +46,10 @@ pair automates that step for **non-production** environments: on every deploy th
 registers **itself** into the target group whose **name exactly equals the EB environment name**.
 
 Originally built in `api2`; ported to `worker2` on 2026-07-28 with three security hardenings
-(instance-profile credentials, native-PHP IMDSv2, fail-closed token handling). **`worker2` is now
-the reference implementation — `api2`'s copy has known defects, see below.**
+(instance-profile credentials, native-PHP IMDSv2, fail-closed token handling), and to `saml`
+(SAML SSO Gateway) on 2026-08-27 as a byte-faithful copy of the hardened `worker2` variant.
+**`worker2` is now the reference implementation — port from it, not from `api2`, whose copy has
+known defects (see below).**
 
 Non-prod `worker2` environments need this because they are reached **over HTTP for manual job
 invocation**, not through SQS.
@@ -50,8 +64,8 @@ invocation**, not through SQS.
 2. **`ebs/register_instance_to_shared_application_load_balancer.php`**
    - Reads the instance id and region from
      `/var/app/current/storage/instance-id.txt` and `storage/region.txt` (written earlier by the
-     `_shared/040-write-instance-id.sh` / `041-write-region.sh` prebuild hooks), falling back to a
-     direct **IMDSv2** lookup.
+     `_shared/040-write-instance-id.sh` / `041-write-region.sh` hooks — see the layout note
+     below), falling back to a direct **IMDSv2** lookup.
    - Reads the EB environment name via `get-config container -k environment_name`.
    - Uses the AWS SDK (`aws/aws-sdk-php`) ELBv2 client to `DescribeTargetGroups` and selects the
      target group whose **`TargetGroupName` is an exact string match** for the environment name —
@@ -64,13 +78,23 @@ invocation**, not through SQS.
 
 | Hook | Provides |
 |---|---|
-| `prebuild/_shared/040-write-instance-id.sh` | `storage/instance-id.txt` |
-| `prebuild/_shared/041-write-region.sh` | `storage/region.txt` |
-| `prebuild/_shared/042-write-eb-environment.sh` | `storage/eb-environment.txt` |
+| `_shared/040-write-instance-id.sh` (run via a phase wrapper) | `storage/instance-id.txt` |
+| `_shared/041-write-region.sh` (run via a phase wrapper) | `storage/region.txt` |
+| `_shared/042-write-eb-environment.sh` (run via a phase wrapper) | `storage/eb-environment.txt` |
 | `postdeploy/015_install_composer.sh` | `vendor/` (the AWS SDK) |
 
 Renumber it below `015` and the SDK autoloader does not exist yet.
 
+### Real on-disk hook layout — `_shared` + thin phase wrappers (corrected 2026-08-27)
+
+The canonical `040`/`041`/`042` scripts live at **`.platform/hooks/_shared/0xx.sh`** — **not**
+under `prebuild/`, as earlier revisions of this doc stated. Each deploy phase that needs one
+carries a **thin wrapper** in its own hook dir (`.platform/hooks/prestart/0xx.sh`,
+`.platform/hooks/postdeploy/0xx.sh`) that just runs `bash ../_shared/0xx.sh`. In the `worker2`
+and `saml` trees, `040`/`041` have both a `prestart` and a `postdeploy` wrapper, while `042` has
+a `postdeploy` wrapper only (no `prestart` copy). When porting, copy the canonical `_shared`
+script **and** the phase wrappers the tier needs — the wrappers are what actually execute.
+
 ### `042-write-eb-environment.sh` — the EB environment name, cached to disk (2026-08-04)
 
 Added to the same `_shared` hook family (plus a postdeploy hook) in **both `api2` and `worker2`**,
@@ -95,6 +119,21 @@ an identical `015_install_composer.sh`; and the same `get-config environment -k
 convention already used by `.ebextensions/git.php`. Check these four before porting the pair to
 any other 2.0 tier.
 
+**`saml` port (2026-08-27) — the two prerequisites a bare tier is missing.** `saml` had *none*
+of the hook family (prebuild was `git.sh` only, postdeploy was `015_install_composer.sh` only,
+no `ebs/` dir), so the port copied the canonical `_shared/040/041/042` scripts, their phase
+wrappers, `060_…​.sh`, and the hardened `ebs/register_instance_to_shared_application_load_balancer.php`.
+The two prerequisites it did **not** already meet:
+
+- **`aws/aws-sdk-php` was absent** from `composer.json` — added `aws/aws-sdk-php: ^3.337`
+  (the SDK's ELBv2 client is what the script uses). **`composer.lock` + `vendor/` must be
+  regenerated** with `composer require aws/aws-sdk-php:^3.337` before deploy (a developer step;
+  not done in the porting session).
+- **Stale `config.platform.php` pin.** `saml` pinned `7.2.33`, but the EB box runs PHP 8.5 (AL2023
+  / platform 4.13.1) and `aws-sdk-php ^3.337` needs PHP ≥ 8.1, so the stale pin would block
+  dependency resolution. Corrected to `8.1.0`. **Check the platform pin on any tier before
+  porting** — a low pin silently blocks the SDK install.
+
 ## Credentials — instance profile only (decision, 2026-07-28)
 
 **Deploy-time AWS credentials come from the EC2 instance profile. Never from source, never from
@@ -141,6 +180,12 @@ implementation instead:
   group name first when a non-prod env is unreachable after a deploy.
 - **Exit 0 hides failures.** Registration problems will not show in deploy status — read
   `/var/log/eb-hooks.log` on the instance.
+- **`saml` does nothing until it has a non-prod env + matching target group.** The team KB lists
+  `saml`'s only environment as `saml-production`, which this hook **self-skips**. The `saml` port
+  registers a target only on a **non-prod** `saml` env, and only if (a) that env's EC2 instance
+  profile carries the two IAM actions below (Describe scoped by `aws:RequestedRegion`, Register
+  scoped to the **non-prod** target-group ARN — never `targetgroup/*/*`), and (b) a target group
+  exists named **exactly** the non-prod env name. Naming equality is the whole contract.
 - **The hook turns on reachability; it does not secure it.** The target group and listener already
   exist by convention, but because this hook is what actually puts non-prod instances behind the
   shared ALB, the **listener rules and security groups must restrict non-prod to internal/VPN
@@ -172,6 +217,13 @@ which lists the other hooks but not `060` — pending an elevated-doc update.
 
 ## Change history
 
+- 2026-08-27 — Ported the hardened `worker2` hook pair to **`saml`** (SAML SSO Gateway): copied
+  `_shared/040/041/042`, their prestart/postdeploy wrappers, `060_…​.sh`, and the instance-profile
+  `ebs/register_instance_to_shared_application_load_balancer.php`. Added `aws/aws-sdk-php: ^3.337`
+  to `saml/composer.json` and corrected its stale `config.platform.php` pin `7.2.33 → 8.1.0`
+  (lock/vendor still to be regenerated by a developer). Also **corrected this doc's file paths**:
+  the canonical `040/041/042` scripts live at `.platform/hooks/_shared/`, not `prebuild/_shared/`,
+  and run via thin per-phase wrappers. (jcardinal)
 - 2026-08-04 — Added `_shared/042-write-eb-environment.sh` (+ a postdeploy hook) to **api2 and
   worker2**, caching the EB environment name to disk from `get-config` → `$EB_ENVIRONMENT_NAME` →
   the IMDS tag. Read from a file rather than shelled out to at use time because its first consumer

package/knowledge/INDEX.md

@@ -4,7 +4,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 19 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 20 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 28 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)
@@ -18,7 +18,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 69 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 70 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 57 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 25 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 13 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)

package/knowledge/clients/nychh/INDEX.md

@@ -2,5 +2,7 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
+| [NYCHH NetSuite → TransferOrders import (stocking-flag routing, PO bridges, origin location)](features/netsuite-transfer-order-import.md) | 1.0 | NYCHH's NetSuite **transfer orders are represented as NetSuite sales orders** (same as the GroWrk pattern), so the shared NetSuite → TOGa Supply importer (`App_ | library/app/api/toga2.php, library/app/api/netsuite/rest.php, library/app/netsuite.php, worker/crons/toga2/netsuite/sync_togasupply_hh.php, worker/crons/toga2/netsuite/common_sync_togasupply.php |
 | [NYCHH PO links are UPSTREAM — the downstream SO→PO route returns empty](features/po-number-upstream-direction.md) | 2.0 | NYCHH's sales orders are created **from the customer's purchase order**, so their SO↔PO links live in the **upstream** table `PurchaseOrders_SalesOrders` (route | _underscore/Model/Client/SalesOrder.php, _underscore/Trait/Netsuite/SalesOrder.php, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts, dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql, dbchanges2/Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql |
-| [NYC Health & Hospitals](profile.md) | 2.0 | NYC Health & Hospitals (NYCHH) is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Nychh`. | dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql |
+| [NYCHH transfer-order 2.0 model — inventory quantities + V2 field enablement](features/transfer-order-inventory-quantities.md) | 2.0 | The 2.0 (`_underscore`) side of NYCHH transfer-order support: a **two-branch inventory quantity model** on the NYCHH `Item` override, plus the **client-override | _underscore/Model/Nychh/Item.php, _underscore/Model/Nychh/TransferOrder.php, _underscore/Model/Nychh/TransferOrderStage.php, _underscore/Model/Client/TransferOrder.php, dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql, dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql |
+| [NYC Health & Hospitals](profile.md) | 2.0 | NYC Health & Hospitals (NYCHH) is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Nychh`. | dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql, dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql |

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

@@ -0,0 +1,143 @@
+---
+title: "NYCHH NetSuite → TransferOrders import (stocking-flag routing, PO bridges, origin location)"
+framework: "1.0"
+repo: library
+project: Library
+client: nychh
+type: client-feature
+status: active
+updated: 2026-08-27
+owners: [jcardinal]
+files:
+  - library/app/api/toga2.php
+  - library/app/api/netsuite/rest.php
+  - library/app/netsuite.php
+  - worker/crons/toga2/netsuite/sync_togasupply_hh.php
+  - worker/crons/toga2/netsuite/common_sync_togasupply.php
+related:
+  - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
+  - ../../../1.0/apps/library/features/toga2-api-client-and-bridge.md
+  - ../../../1.0/apps/library/features/netsuite-suiteql-rest-shim.md
+  - ../../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md
+  - ../../growrk/features/transfer-order-flow.md
+  - ./transfer-order-inventory-quantities.md
+  - ../profile.md
+---
+
+## Summary
+
+NYCHH's NetSuite **transfer orders are represented as NetSuite sales orders** (same as the GroWrk
+pattern), so the shared NetSuite → TOGa Supply importer (`App_Api_Toga2::sync*FromNetsuite`) must
+decide, per order, whether to write it to `Client_Nychh.SalesOrders` or `Client_Nychh.TransferOrders`.
+This doc covers the **1.0-side ingestion**: the routing signal, the PO↔order bridge links, transfer-order
+origin/destination location resolution, the item-fulfillment transfer-order line link, and the
+transfer-order status map. The **2.0-side** (quantity model + the model/ACL work that lets the
+TransferOrder POST succeed) is in
+[NYCHH transfer-order inventory & quantities](./transfer-order-inventory-quantities.md).
+
+**End-to-end verified this session:** a transfer order imported into `Client_Nychh.TransferOrders`
+after deploy. One open edge case remains (order 128829, below).
+
+## Routing signal — the NetSuite stocking flag, NOT the dollar amount
+
+Route by the custom NetSuite checkbox **`custbody_stocking_order`** (internal id **7097**), not by
+total/hold:
+
+- **CHECKED** = a *stocking order* (how stock comes **IN**) → `Client_Nychh.SalesOrders`.
+- **UNCHECKED** = a *transfer order* (how stock goes **OUT**) → `Client_Nychh.TransferOrders`.
+
+`App_Api_Toga2::isTransferOrder()` was rewritten to read this flag through a new private
+`isStockingOrder()` that normalizes NetSuite's `'T'`/`'F'` / bool / int representations. A new
+private `linkPurchaseOrderToTransferOrder()` mirrors the existing sales-order PO linker (below).
+
+> **⚠ The old heuristic — `total === 0` + `custbody_asi_hold` / `holdInvoice` — was WRONG for NYCHH
+> and is gone.** NYCHH does **not** set the hold flag, so under the old rule every order matched as
+> a sales order and `TransferOrders` stayed empty. The dollar amount is **ignored entirely** now.
+> (GroWrk's own `holdInvoice + total===0` signal — see
+> [GroWrk transfer order flow](../../growrk/features/transfer-order-flow.md) — is client-specific and
+> not universal; the TO-detection signal must be read per client.)
+
+**Routing is opt-in per client, default OFF.** The shared engine only routes to TransferOrders when
+the wrapper enables it. NYCHH's wrapper sets
+`const IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING = true;` in
+`worker/crons/toga2/netsuite/sync_togasupply_hh.php`; every other client inherits the default (off)
+and behaves exactly as before.
+
+## PO ↔ order bridge links (header + line)
+
+A single NetSuite PO is bridged to whichever order table the order landed in, at both header and
+line level; links are idempotent (line matching is by shared item `uuid`):
+
+| Order routed to | Header bridge | Line bridge |
+|---|---|---|
+| stocking → SalesOrders | `PurchaseOrders_SalesOrders` | `PurchaseOrderItems_SalesOrderItems` |
+| transfer → TransferOrders | `PurchaseOrders_TransferOrders` | `PurchaseOrderItems_TransferOrderItems` |
+
+`linkPurchaseOrderToTransferOrder()` is the new transfer-order counterpart to the existing
+sales-order linker. See the shared
+[SO↔PO bridge direction](../../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md)
+doc for the bridge naming convention.
+
+## Transfer-order origin/destination location resolution
+
+`TransferOrders.originLocationId` is **NOT NULL**, so a missing origin fails the V2 insert with
+**EV-10** ("originLocationId cannot be null"). Two fixes were needed:
+
+1. **The line SuiteQL never selected the line location.** `App_Api_Netsuite_Rest::listSalesOrders()`
+   line query now selects `tl.location` and `BUILTIN.DF(tl.location) AS location_name`. The line
+   shim already *read* these fields, but they were never *selected*, so they were always null — see
+   the [SuiteQL/REST shim](../../../1.0/apps/library/features/netsuite-suiteql-rest-shim.md).
+2. **Header-location fallback.** In `toga2.php`, origin resolution falls back to the **first
+   line-item location** when the NetSuite header location is empty.
+
+> **OPEN edge case (pending developer decision):** NetSuite sales order **128829** has **no
+> location** on the header *or* on any SuiteQL line, so neither rule resolves an origin. A
+> default-origin rule is proposed — candidate: NYCHH warehouse **Location 75** /
+> `c_netsuiteInternalLocationId` **117** — but not yet applied. Until decided, 128829 cannot import.
+
+## Item-fulfillment transfer-order line link
+
+`ItemFulfillmentItems.transferOrderItemId` must populate so the 2.0 stock-out quantity calc can tie
+a fulfillment back to its transfer-order line. In `syncItemFulfillmentFromNetsuite`:
+
+- added `itemFulfillmentItems.transferOrderItem.uuid` to the GET `fields` allowlist,
+- null-guarded the dedup lookup (`?? null`),
+- the header IF POST sets `transferOrder` when applicable.
+
+## Transfer-order status map
+
+`syncTransferOrderFromNetsuite`'s status switch was expanded to cover the real NetSuite statuses:
+**Billed**, **Pending Billing**, **Pending Billing-Partially Fulfilled** → `received` / `inTransit`.
+The **default** now **logs and defaults to `'pending'`** instead of throwing. An unmapped "Billed"
+status was previously throwing (and being swallowed), which is why order 128829 never imported.
+
+`App_NetSuite::getCustomFieldValue()` (`library/app/netsuite.php`) was hardened with `?? []` / `?? null`
+guards: 1.0 targets PHP 7.2 and any PHP warning on that path terminates the cron.
+
+## Gotchas / known issues
+
+- **Order 128829 (no location anywhere) is unresolved** — see the origin-resolution section. Do not
+  assume the importer is broken if this single order is stuck; every located order imports.
+- **Routing is gated by the wrapper constant.** If a future client should route transfer orders,
+  add `const IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING = true;` before its
+  `require_once 'common_sync_togasupply.php';` — and confirm that client actually sets
+  `custbody_stocking_order` in NetSuite. Absent the flag, everything lands in SalesOrders.
+- **`custbody_stocking_order` must reach the shim.** `fetchSalesOrderById()` now carries the field
+  via `customFieldList`; a missing custom field read returns null → the order routes as a transfer
+  order (unchecked = transfer). Verify the field is populated in NetSuite before trusting the split.
+
+## Change history
+
+- 2026-08-27 — Built NYCHH transfer-order ingestion end-to-end. **Routing by `custbody_stocking_order`
+  (id 7097), not dollar amount** (`isTransferOrder()` rewritten + new `isStockingOrder()` normalizer);
+  the old `total===0 + hold-flag` heuristic was wrong for NYCHH (no hold flag set → everything landed
+  in SalesOrders) and is removed. Routing is opt-in per client via
+  `IS_ENABLED_TRANSFER_ORDER_STOCKING_FLAG_ROUTING` (default off; NYCHH true). Added the
+  `PurchaseOrders_TransferOrders` / `PurchaseOrderItems_TransferOrderItems` bridge linker; resolved TO
+  origin (line SuiteQL now selects `tl.location`, header-empty falls back to first line location);
+  linked item fulfillments to their transfer-order line (`transferOrderItem.uuid`); expanded the TO
+  status map (Billed / Pending Billing → received/inTransit, default `pending` instead of throwing);
+  hardened `getCustomFieldValue()` for PHP 7.2. A transfer order imported into
+  `Client_Nychh.TransferOrders` after deploy. **Open:** order 128829 has no location on header or any
+  line — default-origin rule (candidate Location 75 / `c_netsuiteInternalLocationId` 117) pending the
+  developer's decision. (jcardinal)

package/knowledge/clients/nychh/features/transfer-order-inventory-quantities.md

@@ -0,0 +1,116 @@
+---
+title: "NYCHH transfer-order 2.0 model — inventory quantities + V2 field enablement"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: nychh
+type: client-feature
+status: active
+updated: 2026-08-27
+owners: [jcardinal]
+files:
+  - _underscore/Model/Nychh/Item.php
+  - _underscore/Model/Nychh/TransferOrder.php
+  - _underscore/Model/Nychh/TransferOrderStage.php
+  - _underscore/Model/Client/TransferOrder.php
+  - dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql
+  - dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql
+related:
+  - ../../../2.0/apps/_underscore/features/acl-permission-chain.md
+  - ../../../2.0/apps/api2/features/v2-api-error-codes.md
+  - ../../growrk/features/transfer-order-flow.md
+  - ./netsuite-transfer-order-import.md
+  - ../profile.md
+---
+
+## Summary
+
+The 2.0 (`_underscore`) side of NYCHH transfer-order support: a **two-branch inventory quantity
+model** on the NYCHH `Item` override, plus the **client-override model declarations and ACL rows**
+that let a NetSuite-sourced TransferOrder actually POST through the V2 API. The 1.0 ingestion that
+feeds these POSTs is in
+[NYCHH NetSuite → TransferOrders import](./netsuite-transfer-order-import.md).
+
+The general, framework-level lessons from the field-exposure work here are recorded on the shared
+[ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md) and
+[V2 API error codes](../../../2.0/apps/api2/features/v2-api-error-codes.md) docs; this doc keeps the
+NYCHH-specific composition.
+
+## NYCHH-only quantity calculations (two-branch inventory model)
+
+Per the 2026-08-17 "TOGa Supply" meeting. **NYCHH ONLY** — the overrides live on the client model
+`_Model_Nychh_Item` (`_underscore/Model/Nychh/Item.php`), not the base. Stocking orders bring stock
+**in**, transfer orders send it **out**, so the quantities reflect that direction:
+
+| Quantity | Definition |
+|---|---|
+| **on hand** | `received` (PO item receipts) − `fulfilled` (transfer-order item fulfillments) |
+| **available** | `on hand` − `committed` |
+| **fulfilled** | Σ shipped transfer-order fulfillments |
+| **backordered** | `ordered` − `received` |
+
+`_qtyOnOrder` was added alongside these. The stock-in side reads PO receipts; the stock-out side
+reads transfer orders (which is why the 1.0 importer must populate
+`ItemFulfillmentItems.transferOrderItemId` — see the import doc).
+
+## V2 field enablement — how the TransferOrder POST was made to work
+
+Posting a NetSuite-sourced transfer order that carries NetSuite custom fields required **every** part
+of the custom-field recipe on the NYCHH client DB. Each missing part surfaced as a distinct V2 error,
+peeled in order:
+
+1. **Client-override model must DECLARE the custom field.** The framework resolves
+   `_Model_Nychh_X extends _Model_Client_X`, and the NetSuite `c_` declarations come from
+   `_Trait_Netsuite_X`. Created:
+   - `_underscore/Model/Nychh/TransferOrder.php` —
+     `class _Model_Nychh_TransferOrder extends _Model_Client_TransferOrder { use _Trait_Netsuite_TransferOrder; }`
+     (declares `c_netsuiteInternalSalesOrderId`) → fixes the **EO-1** 500.
+   - `_underscore/Model/Nychh/TransferOrderStage.php` —
+     `class _Model_Nychh_TransferOrderStage extends _Model_Client_TransferOrderStage { use _Trait_Netsuite_TransferOrderStage; }`
+     (declares `c_netsuiteInternalTransferOrderStatus`) → fixes **EV-12** `invalidSearchableField`.
+2. **ACL write grant** — an `AclCustomFieldPermissions` row (roleId 1, `isWritable 1`) for
+   transfer-orders `c_netsuiteInternalSalesOrderId` (record 312) → fixes **EV-9**.
+   `dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql`.
+3. **Searchable identifier** — for a nested FK resolved *by a custom field*, that field's
+   `CustomRecordFields.isIdentifier` must be `1`. Set `isIdentifier=1` on
+   `c_netsuiteInternalTransferOrderStatus` (recordId 351) → fixes **EV-12**
+   `searchableIdentifierFields:[id]`.
+   `dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql`.
+
+> **There is NO ACL/metadata caching layer in the 2.0 V2 API.** Applying these ACL/metadata rows
+> takes effect on the **very next request** — there is no cache to invalidate and no cache-bust step.
+> (This corrects an earlier assumption that a cache had to be busted, which sent debugging down a
+> dead end.) Recorded framework-wide on the
+> [ACL permission chain](../../../2.0/apps/_underscore/features/acl-permission-chain.md).
+
+## `isActive` is defaulted in the ORM, not sent in the payload (shared model)
+
+`TransferOrders.isActive` is **NOT NULL**, but `isActive` is **not a registered/writable V2 field** —
+adding `'isActive' => 1` to the POST payload throws **EV-8** ("field does not exist"). The correct
+fix is to default it in the ORM: `_underscore/Model/Client/TransferOrder.php` now declares
+`public $isActive = [self::FIELD_BOOLEAN, self::FIELDOPT_DEFAULT => true];`, so the ORM writes `1` on
+insert without a payload key. This is a **shared** (`_Model_Client_TransferOrder`) change — the
+pattern (default a NOT NULL non-writable column in the model, never send it) is on the
+[V2 API error codes](../../../2.0/apps/api2/features/v2-api-error-codes.md) map under EV-8.
+
+## Gotchas / known issues
+
+- **A custom field is writable/searchable ONLY when BOTH the model declares it (via the NetSuite
+  trait on the client-override model) AND the ACL/metadata rows exist.** Declaring without the ACL
+  row, or granting the ACL without the declaration, each fails with its own error — see the peeled
+  sequence above.
+- **These quantity overrides are NYCHH-only.** They live on `_Model_Nychh_Item`; do not lift them to
+  the base `_Model_Client_Item` — other clients do not have the stocking/transfer two-branch model.
+
+## Change history
+
+- 2026-08-27 — Built the NYCHH two-branch inventory quantity model on `_Model_Nychh_Item` (on hand =
+  received − fulfilled; available = on hand − committed; fulfilled = Σ shipped TO fulfillments;
+  backordered = ordered − received; added `_qtyOnOrder`), per the 2026-08-17 TOGa Supply meeting.
+  Enabled the NetSuite-sourced TransferOrder POST by creating the NYCHH client-override models
+  `_Model_Nychh_TransferOrder` / `_Model_Nychh_TransferOrderStage` (each `use`s its
+  `_Trait_Netsuite_*` to declare the `c_` field), adding the `AclCustomFieldPermissions` write grant
+  (2026-08-27a) and setting `CustomRecordFields.isIdentifier=1` on
+  `c_netsuiteInternalTransferOrderStatus` (2026-08-27b). Defaulted the shared
+  `_Model_Client_TransferOrder::$isActive` in the ORM (NOT NULL, non-writable → EV-8 if sent).
+  Confirmed there is **no ACL/metadata cache** — rows apply on the next request. (jcardinal)

package/knowledge/clients/nychh/profile.md

@@ -15,15 +15,19 @@ project: _Underscore
 client: nychh
 type: profile
 status: active
-updated: 2026-08-26
+updated: 2026-08-27
 owners: ["jcardinal", "apeterson", "bala"]
 files:
   - dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql
   - dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql
+  - dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql
+  - dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql
 related:
   - ../../2.0/apps/_underscore/features/tracking-number-bridges.md
   - ../../2.0/apps/_underscore/features/tableview-joins.md
   - ./features/po-number-upstream-direction.md
+  - ./features/netsuite-transfer-order-import.md
+  - ./features/transfer-order-inventory-quantities.md
   - ../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md
 ---
 
@@ -53,6 +57,14 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   `macAddress` synced from the NetSuite serial (inventory-number) record, closing the gap where a
   tag added after the ItemShip never bumps the fulfillment sync. See
   [NYCHH Asset-Tag Backfill](../../2.0/apps/worker2/features/nychh-asset-tag-backfill.md).
+- **Transfer orders (NetSuite sales orders → `TransferOrders`)** — NYCHH's NetSuite transfer orders
+  arrive as sales orders; the 1.0 importer routes them by the `custbody_stocking_order` flag (not the
+  dollar amount), bridges the PO, and resolves origin/destination locations. See
+  [NYCHH NetSuite → TransferOrders import](./features/netsuite-transfer-order-import.md).
+- **Two-branch inventory quantities + TransferOrder V2 enablement** — NYCHH-only on-hand/available/
+  fulfilled/backordered model on `_Model_Nychh_Item`, plus the client-override models + ACL rows that
+  let a NetSuite TransferOrder POST succeed. See
+  [NYCHH transfer-order inventory & quantities](./features/transfer-order-inventory-quantities.md).
 
 - **PO links are UPSTREAM (`PurchaseOrders_SalesOrders`), not downstream.** The downstream
   `sales-order-purchase-orders` route returns an empty array for NYCHH by design, and the shared

package/package.json

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