toga-ai 1.0.706 → 1.0.708

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

@@ -11,6 +11,7 @@
 | [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | `App_Api_Toga2` in `library/app/api/toga2.php` orchestrates bidirectional sync between TOGA 2 and TOGaDesk. | library/app/api/toga2.php |
 | [App_Email Queued Sending & Attachments (Common.EmailsQueued)](features/email-queue-attachments.md) | `App_Email::send()` can either send **inline** (PHPMailer talks to SES right there) or **queue** the message: `base64(serialize($this))` is inserted into `Commo | library/app/email.php, library/phpmailer/class.phpmailer.php, worker/crons/notifications/infrastructure/send_emails.php, worker/crons/notifications/covid/send_covid_pending_vaccination_approval.php, togadesk/desk/includes/functions.php |
 | [Branded HTML Email Templates (App_Email_Template)](features/email-templates.md) | `App_Email_Template` (`app/email/template.php`) is the base class for branded HTML emails in the 1.0 (`App_`) framework. | library/app/email/template.php, library/app/email/agilant.php |
+| [App_Email Side Effects & Test Mode (how to send a real email that writes nothing)](features/email-test-mode-and-write-free-sends.md) | `App_Email::send()` is **not** side-effect free. | library/app/email.php, library/app/framework.php |
 | [Error Capture in 1.0 (App_Error_Capture → shared 2.0 Logs DB)](features/error-capture-1-0.md) | The 1.0 side of the platform error-reporting pipeline (TRUE-78188). | library/app/error/capture.php, library/app/error.php, library/app/exception/business.php, library/app/api/toga2.php, library/app/cloud.php, worker/config.worker.ini, worker/crons/toga2/compass/workflow/1_transmit_compass_sales_orders_to_mits.php |
 | [HTTP 500 Error Monitor (App_SystemMonitor_500Error) — and why its \"Error Type\" is not a diagnosis](features/http-500-error-monitor.md) | `App_SystemMonitor_500Error` (`library/app/systemmonitor/500error.php`, title **"HTTP 500 Error Alert"**) is the 1.0 system monitor that watches **`Logs.Api` fo | library/app/systemmonitor/500error.php, worker/crons/infrastructure/system_monitors.php, api2/Controller/Index.php, _underscore/Error.php |
 | [1.0 MVC Page Pattern & New-App Skeleton](features/mvc-page-pattern-and-app-skeleton.md) | This is the **reusable recipe for standing up a new 1.0 (`App_`) application** and for adding pages to one — the folder-based MVC routing, the page lifecycle, t | library/app/framework.php, library/app/frameworkindex.php, library/app/mvc.php, library/app/database.php, library/app/model.php, library/app/config.php |

package/knowledge/1.0/apps/library/features/email-queue-attachments.md

@@ -6,8 +6,8 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-20
-owners: ["mhammontree"]
+updated: 2026-08-31
+owners: ["mhammontree", "bala"]
 files:
   - library/app/email.php
   - library/phpmailer/class.phpmailer.php
@@ -16,6 +16,7 @@ files:
   - togadesk/desk/includes/functions.php
 related:
   - ./email-templates.md
+  - ./email-test-mode-and-write-free-sends.md
   - ../architecture.md
   - ../../togadesk/features/notifications.md
 ---
@@ -105,6 +106,9 @@ togadesk first, let the queue drain empty, *then* worker.
   no DB, no SMTP, confirmed failing against pre-fix HEAD.
 
 ## Change history
+- 2026-08-31 — Cross-linked the companion doc on `send()`'s other side effects (the `Logs.Email`
+  write and `setIsLogEnabled(false)`, the `OUTBOUND_EMAIL_ENABLED` queue branch) and on how
+  `test_mode` rewrites the recipient list to `dev_email_to` (bala)
 - 2026-08-20 — TRUE-80952: queued attachments now embed base64 bytes (`embedAttachmentsForQueue()`
   + `AddStringAttachment`) instead of paths that do not exist on the drain host; added
   `MAX_QUEUED_ATTACHMENT_BYTES` with inline-send fallback and a scoped warning guard around the

package/knowledge/1.0/apps/library/features/email-test-mode-and-write-free-sends.md

@@ -0,0 +1,128 @@
+---
+title: App_Email Side Effects & Test Mode (how to send a real email that writes nothing)
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-08-31
+owners: ["bala"]
+files:
+  - library/app/email.php
+  - library/app/framework.php
+related:
+  - ./email-queue-attachments.md
+  - ./email-templates.md
+  - ../architecture.md
+---
+
+## Summary
+
+`App_Email::send()` is **not** side-effect free. By default it INSERTs a log row, and under
+several ordinary conditions it INSERTs a queue row and sends nothing at all. Separately, it
+**rewrites the recipient list** in test mode. Anyone writing a dry-run script, a template
+preview, or a "let me just fire one test email" harness in the 1.0 tier needs both facts, or
+they will either pollute a production table or wonder why the intended recipient never got the
+mail.
+
+Verified against `library/app/email.php` on 2026-08-31.
+
+## What `send()` writes
+
+| Write | When | How to suppress |
+|---|---|---|
+| `Logs.Email` row (`App_Model_Logs_Email`) | every **inline** send, success or failure | `setIsLogEnabled(false)` |
+| `Common.EmailsQueued` row (`App_Model_Common_EmailsQueued`) | `queueForSending` truthy, **or** outbound email is disabled and `sendEmailEvenIfOutboundEmailIsDisabled` is false | `setQueueForSending(false)` + `sendEmailEvenIfOutboundEmailIsDisabled = true` |
+
+The queue-vs-send decision is a single condition (`email.php` ~L313):
+
+```php
+if ($this->queueForSending || (!$this->sendEmailEvenIfOutboundEmailIsDisabled && !$isOutboundEmailEnabled)) {
+```
+
+`$isOutboundEmailEnabled` is read from the `Defaults` table
+(`setting = 'OUTBOUND_EMAIL_ENABLED'`), so **an environment can silently convert your "send" into
+a queue insert** with no code change on your side. The log write is inside the `else` branch, so a
+queued message writes the queue row and **no** log row.
+
+## The three switches for a genuinely write-free send
+
+All three are required — any one of them left at its default reintroduces a write or swallows the
+send:
+
+1. `setQueueForSending(false)` — do not insert into `Common.EmailsQueued`.
+2. `sendEmailEvenIfOutboundEmailIsDisabled = true` — do not fall into the queue branch just
+   because the `Defaults` flag is off.
+3. `setIsLogEnabled(false)` — do not insert into `Logs.Email`.
+
+## `App_Email` only ever *narrows* the recipient list
+
+This is worth stating plainly because people assume the opposite when a test email "goes
+somewhere unexpected". `send()` does exactly two things to the addresses you set:
+
+- **Suppression** — every `to`/`cc`/`bcc` entry is dropped if
+  `App_Model_Common_EmailSuppressionList::isOkayToSendEmailTo()` says no.
+- **Test mode** — if `forceInTestMode` is set **or** config `internal.test_mode == 1`, the whole
+  `to`/`cc`/`bcc` list is **discarded** and replaced with the single config value
+  `email.dev_email_to`. The body is prefixed with a red `DEVELOPMENT MODE - Intended Recipients:
+  …` banner naming who *would* have received it. With `test_mode = 1` and no `dev_email_to`
+  configured, `send()` **throws**.
+
+There is **no** hidden bcc, no admin copy, no silent additional recipient anywhere in `send()`.
+If someone received a test message, they were on your list or they are `dev_email_to`.
+
+**Practical consequence:** a local/alpha/beta config has `test_mode = 1`, so *only* `dev_email_to`
+ever receives your test. To have a second person actually receive a test message you must run the
+script **on the worker server**, whose `config.worker.ini` has `test_mode = 0` — and at that point
+your recipient list is real, so get it right.
+
+## `cronInitialization()` writes too
+
+`App_Framework::cronInitialization()` (`library/app/framework.php` ~L689) INSERTs a
+`CronJobExecutions` row before your code runs (and UPDATEs it at the end). A write-free script
+must **not** call it. It also does the two things you still need, so do them yourself:
+
+```php
+set_time_limit(900);
+date_default_timezone_set('America/Chicago');
+```
+
+Call `App_Framework_Worker::initialize()` (or the app's equivalent) for config/registry/DB, and
+stop there.
+
+## Recipe — a dry-run email script in the 1.0 worker tier
+
+1. Bootstrap with `App_Framework_Worker::initialize()` only; set `set_time_limit()` and
+   `date_default_timezone_set()` yourself. **Do not** call `cronInitialization()`.
+2. Read your sample data with a **single SELECT** — no models that `save()`, no api2 calls.
+3. Build the mail exactly as the real code does (same template class, same subject, same S3
+   fetches) so you are testing the real body, not a paraphrase of it.
+4. Set the three switches above.
+5. Print, before sending, which attachments resolved and their byte sizes — a missing PDF is
+   otherwise invisible (see `email-queue-attachments.md`: PHPMailer 5 sends anyway).
+
+Run it with the framework repos on the include path:
+
+```
+php -d include_path=".;<library>;<_underscore>" <path/to/script>.php
+```
+
+## Gotchas
+
+- **A "successful" local test proves less than it looks.** `test_mode = 1` collapses both the
+  queue path (see `email-queue-attachments.md`) and the recipient list. Two different behaviors
+  you cannot exercise locally.
+- **Deleting the log write is not the same as being read-only.** `setIsLogEnabled(false)` only
+  suppresses `Logs.Email`; the queue insert has its own switch and fires *instead of* sending.
+- **Dry-run harness scripts are throwaway.** Keep them out of the repo — they carry hardcoded
+  recipient lists and bypass the real gating. Build one, use it, delete it; document the
+  *technique* here rather than committing the file.
+
+## Change history
+- 2026-08-31 — Documented that `App_Email::send()` writes `Logs.Email` unless
+  `setIsLogEnabled(false)`, that the queue branch also fires when `OUTBOUND_EMAIL_ENABLED` is off,
+  that `cronInitialization()` INSERTs `CronJobExecutions`, and that `send()` only ever narrows
+  recipients (suppression list + `test_mode` → `dev_email_to` with a DEVELOPMENT MODE banner —
+  never adds one). Written up after building a throwaway write-free harness for the Prudential
+  order emails (bala)

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)_ — 22 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 23 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 31 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **dbchanges** (Database Changes) _(framework core)_ — 1 doc(s) → [1.0/apps/dbchanges/INDEX.md](1.0/apps/dbchanges/INDEX.md)
 - **worker1.5** (Worker 1.5) — 0 doc(s) → [1.0/apps/worker1.5/INDEX.md](1.0/apps/worker1.5/INDEX.md)

package/knowledge/clients/nychh/INDEX.md

@@ -5,5 +5,5 @@
 | [NYCHH inventory-adjustment → item-fulfillment linking (direct FK columns, REST)](features/netsuite-inventory-adjustment-fulfillment-link.md) | 1.0 | For NYCHH stock adjustments, the NetSuite **inventory adjustment** carries a link to the **Item Fulfillment** it corrects, on the multi-select body custom field | library/app/api/toga2.php, library/app/api/netsuite/rest.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_hh.php, worker/crons/toga2/netsuite/diagnose_hh_import_inventory_adjustment.php |
 | [NYCHH NetSuite → TransferOrders import (stocking-flag routing, PO bridges, origin location)](features/netsuite-transfer-order-import.md) | 1.0 | NYCHH's NetSuite **transfer orders are represented as NetSuite sales orders** (same as the GroWrk pattern), so the shared NetSuite → TOGa Supply importer (`App_ | library/app/api/toga2.php, library/app/api/netsuite/rest.php, library/app/netsuite.php, worker/crons/toga2/netsuite/sync_togasupply_hh.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/diagnose_hh_stuck_transfer_order.php, dbchanges2/Core/2026-08-27a - TransferOrderUuidSearchableIdentifier.sql, dbchanges2/Client/2026-08-28a - TransferOrderItemsTimestampColumns.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestampColumnsReposition.sql, dbchanges2/Client/2026-08-29 - ItemReceiptTransferOrderIdFieldPermission.sql, dbchanges2/Client/2026-08-29b - ItemReceiptItemTransferOrderItemIdFieldPermission.sql |
 | [NYCHH PO links are UPSTREAM — the downstream SO→PO route returns empty](features/po-number-upstream-direction.md) | 2.0 | NYCHH's sales orders are created **from the customer's purchase order**, so their SO↔PO links live in the **upstream** table `PurchaseOrders_SalesOrders` (route | _underscore/Model/Client/SalesOrder.php, _underscore/Trait/Netsuite/SalesOrder.php, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/hooks/usePurchaseOrderDetails.ts, dbchanges2/Client/2026-08-11b - SalesOrderPurchaseOrdersField.sql, dbchanges2/Client/2026-08-25 - SalesOrderPurchaseOrdersFieldAllClients.sql |
-| [NYCHH transfer-order 2.0 model — inventory quantities + V2 field enablement](features/transfer-order-inventory-quantities.md) | 2.0 | The 2.0 (`_underscore`) side of NYCHH transfer-order support: a **two-branch inventory quantity model** on the NYCHH `Item` override, plus the **client-override | _underscore/Model/Nychh/Item.php, _underscore/Model/Nychh/TransferOrder.php, _underscore/Model/Nychh/TransferOrderStage.php, _underscore/Model/Client/TransferOrder.php, _underscore/Model/Client/TransferOrderItem.php, dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql, dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql |
+| [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/PurchaseOrderItem.php, _underscore/Model/Nychh/TransferOrder.php, _underscore/Model/Nychh/TransferOrderStage.php, _underscore/Model/Client/TransferOrder.php, _underscore/Model/Client/TransferOrderItem.php, dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql, dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql |
 | [NYC Health & Hospitals](profile.md) | 2.0 | NYC Health & Hospitals (NYCHH) is a TOGA 2.0 client on the `_underscore` platform, prod schema `Client_Nychh`. | dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql, dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql, dbchanges2/Client_Nychh/2026-08-27a - TransferOrderCustomFieldWritePermission.sql, dbchanges2/Client_Nychh/2026-08-27b - TransferOrderStageStatusIdentifier.sql, dbchanges2/Client_Nychh/2026-08-28a - TransferOrdersTableView.sql, dbchanges2/Client_Nychh/2026-08-28b - TransferOrdersNavigationEnable.sql, dbchanges2/Client_Nychh/2026-08-28c - TransferOrderRecordAcl.sql, dbchanges2/Client/2026-08-28b - TransferOrderItemsTimestamps.sql |

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

@@ -6,10 +6,11 @@ project: _Underscore
 client: nychh
 type: client-feature
 status: active
-updated: 2026-08-28
+updated: 2026-08-31
 owners: [jcardinal, apeterson]
 files:
   - _underscore/Model/Nychh/Item.php
+  - _underscore/Model/Nychh/PurchaseOrderItem.php
   - _underscore/Model/Nychh/TransferOrder.php
   - _underscore/Model/Nychh/TransferOrderStage.php
   - _underscore/Model/Client/TransferOrder.php
@@ -25,6 +26,8 @@ related:
   - ../../../2.0/apps/toga25-supply/features/transfer-orders-page.md
   - ../../growrk/features/transfer-order-flow.md
   - ./netsuite-transfer-order-import.md
+  - ./netsuite-inventory-adjustment-fulfillment-link.md
+  - ../../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md
   - ../profile.md
 ---
 
@@ -47,20 +50,84 @@ 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:
+Per the 2026-08-17 and 2026-08-27 "TOGa Supply" meetings. **NYCHH ONLY** — the overrides live on the
+client models `_Model_Nychh_Item` (`_underscore/Model/Nychh/Item.php`) and, as of 2026-08-31, the new
+`_Model_Nychh_PurchaseOrderItem` (`_underscore/Model/Nychh/PurchaseOrderItem.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) |
+| **received** (stock-in) | net Σ `InventoryAdjustmentItems.quantityAdjustBy` on the item's **stocking** fulfillments |
+| **on hand** | `received` − `fulfilled` (transfer-order item fulfillments) |
 | **available** | `on hand` − `committed` |
 | **fulfilled** | Σ shipped transfer-order fulfillments |
-| **backordered** | `ordered` − `received` |
+| **backordered** | `ordered` − `received` (floored at 0) |
 
-`_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).
+`_qtyOnOrder` was added alongside these. The stock-out side reads transfer orders (which is why the
+1.0 importer must populate `ItemFulfillmentItems.transferOrderItemId` — see the import doc).
+
+### Stock-in now reads inventory adjustments, NOT PO item receipts (changed 2026-08-31)
+
+Per the **2026-08-27 TOGa Supply meeting**: NetSuite has no "stocking" concept, so the only way stock
+is added is an **inventory adjustment** linked to the stocking order's item fulfillment (never
+directly to the PO). So `_Model_Nychh_Item::_qtyReceived` was changed to the **net
+`SUM(InventoryAdjustmentItems.quantityAdjustBy)`**, joined
+`InventoryAdjustmentItems.itemFulfillmentItemId → ItemFulfillmentItems.salesOrderItemId →
+SalesOrderItems` where `SalesOrderItems.itemId = Items.id`. This **supersedes** the old PO-item-receipt
+basis. Because on-hand and backordered both derive from `received`, they now use adjustments too.
+
+- **The adjustment↔fulfillment link** is the direct FK `InventoryAdjustmentItems.itemFulfillmentItemId`
+  (recent; NULL on older adjustments). Details on
+  [NYCHH inventory-adjustment → item-fulfillment linking](./netsuite-inventory-adjustment-fulfillment-link.md).
+- **Implicit stocking filter:** joining through `ItemFulfillmentItems.salesOrderItemId` counts only
+  **stocking-side** fulfillments — transfer-side fulfillment items have that column NULL — and all
+  Client_Nychh SalesOrders are stocking orders by the import routing.
+- **⚠ Reads 0.00 today, by design.** Verified in prod Client_Nychh 2026-08-31: `InventoryAdjustmentItems`
+  has 292 rows but **0** carry `itemFulfillmentItemId`, and all 351 `ItemFulfillmentItems` are
+  transfer-side (`salesOrderItemId = 0`). INNER JOINs make an unlinked adjustment contribute 0, so every
+  item reads 0 **until the NetSuite integration backfills the link** — expected, not a bug.
+
+## Per-PO-line quantities — `_Model_Nychh_PurchaseOrderItem` (new 2026-08-31)
+
+`_Model_Nychh_PurchaseOrderItem extends _Model_Client_PurchaseOrderItem` gives the **same quantities
+as Item level, but limited to a single purchase-order line** (previously these existed only at Item
+level), which NYCHH needs for PO-specific fulfillment.
+
+- **`_qtyReceived`** — adjustment stock-in (same as Item) but scoped to the PO line via
+  `PurchaseOrderItems_SalesOrderItems` (the PO→SO stocking bridge; see the bridge note below).
+- **`_qtyCommitted`** — Transfer-Order based, scoped to the PO line via
+  `PurchaseOrderItems_TransferOrderItems`, mirroring the Item-level two-branch model.
+- **`_qtyOnHand` / `_qtyAvailable` / `_qtyBackordered` / `_qtyOnOrder`** are **re-declared verbatim** on
+  the child so early-bound `self::` rebinds to the new leaf `_qtyReceived`/`_qtyCommitted` (established
+  framework pattern — a composite `FIELD_SQL` method that calls `self::` must be re-declared on the
+  child, not inherited). `_qtyBackordered` is floored at 0 with `GREATEST`, matching Item level.
+
+> **⚠ Signature must match the parent EXACTLY** when overriding a `FIELD_SQL` static method — an added
+> param type is a **fatal at class load** that `php -l` does NOT catch. Verified this session by
+> php-reviewer + sql-reviewer.
+
+### Which SO↔PO bridge scopes the PO line (they are two directional tables, not duplicates)
+
+The item-level bridges mirror the header-level SO↔PO direction split documented on
+[SO↔PO bridge direction](../../../2.0/apps/_underscore/features/sales-order-purchase-order-bridge-direction.md):
+
+- `PurchaseOrderItems_SalesOrderItems` — **SO items created FROM a PO item** (PO→SO stocking direction);
+  the **populated/canonical** one for stocking (682 rows in prod). PO-line stock-in scopes on this.
+- `SalesOrderItems_PurchaseOrderItems` — PO items created FROM a SO item (3 rows).
+
+Verified 0 SO lines map to >1 PO line, so PO-line `received` **cannot double-count**. Optional deferred
+hardening (not done): a `UNIQUE(purchaseOrderItemId, salesOrderItemId)` on the bridge as defense-in-depth.
+
+- **⚠ PO-level outbound reads 0 until a separate backfill.** `_qtyCommitted` depends on
+  `PurchaseOrderItems_TransferOrderItems`, which is currently **empty (0 rows)** in prod — so PO-level
+  outbound reads 0 until the transfer-order import populates that bridge. Separate import gap, not this change.
+
+### Index coverage / schema
+
+No `dbchanges2` file — pure calculated `FIELD_SQL` in PHP. All correlation columns
+(`InventoryAdjustmentItems.itemFulfillmentItemId`, `ItemFulfillmentItems.salesOrderItemId`,
+`SalesOrderItems.itemId`, both bridge FKs) are already indexed.
 
 ## V2 field enablement — how the TransferOrder POST was made to work
 
@@ -153,11 +220,28 @@ pattern (default a NOT NULL non-writable column in the model, never send it) is
   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.
+- **These quantity overrides are NYCHH-only.** They live on `_Model_Nychh_Item` and
+  `_Model_Nychh_PurchaseOrderItem`; do not lift them to the base `_Model_Client_*` — other clients do
+  not have the stocking/transfer two-branch model.
+- **A 0.00 quantity for NYCHH is expected today, not a bug.** Stock-in reads inventory-adjustment links
+  that are not backfilled yet, and PO-level outbound reads a still-empty
+  `PurchaseOrderItems_TransferOrderItems` bridge (see above).
 
 ## Change history
 
+- 2026-08-31 — **Stock-in flipped from PO item receipts → inventory adjustments** (per the 2026-08-27
+  TOGa Supply meeting: NetSuite has no stocking concept, stock is added only by an inventory adjustment
+  linked to the stocking order's item fulfillment). Changed `_Model_Nychh_Item::_qtyReceived` to net
+  `SUM(InventoryAdjustmentItems.quantityAdjustBy)` joined
+  `itemFulfillmentItemId → ItemFulfillmentItems.salesOrderItemId → SalesOrderItems` (`itemId = Items.id`);
+  on-hand and backordered follow. Added the **NYCHH-only `_Model_Nychh_PurchaseOrderItem`** for per-PO-line
+  quantities (same logic scoped to the PO line via `PurchaseOrderItems_SalesOrderItems` for received and
+  `PurchaseOrderItems_TransferOrderItems` for committed; composite `FIELD_SQL` methods re-declared verbatim
+  to rebind early-bound `self::`; backordered floored with `GREATEST`). Both read **0.00 in prod today** by
+  design — the adjustment↔fulfillment links are not backfilled (292 adjustment items, 0 linked; all 351
+  fulfillment items transfer-side) and `PurchaseOrderItems_TransferOrderItems` is empty. No dbchanges2
+  (pure `FIELD_SQL`; correlation columns already indexed); double-count ruled out (0 SO lines map to >1 PO
+  line). `php -l` clean; php-reviewer 0 critical, sql-reviewer warnings resolved. (jcardinal)
 - 2026-08-28 — Discovered that the transfer-order enablement on **prod and sandbox-client is
   UNTRACKED**: record ACL for 312/313 (roles 1 and 3), their logic-group/expression chain, field ACL
   for all 17 RecordFields, and the `TransferOrderItems.dtCreated`/`dtUpdated` columns all exist with

package/knowledge/clients/prudential/INDEX.md

@@ -6,7 +6,7 @@
 | [Prudential: Dell LCH IOP transmissions (LCHRequestV2)](features/dell-lch-iop-transmissions.md) | 1.0 | Outbound order transmissions from the 1.0 worker tier to Dell's Lifecycle Hub (LCH) ITSM integration. | library/app/api/delllch.php, library/app/apitransaction.php, worker/crons/toga2/prudential/transmissions_to_dell_usa.php, worker/crons/toga2/prudential/transmissions_to_dell_ireland.php, worker/crons/toga2/prudential/transmissions_to_dell_india.php, worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php |
 | [Prudential: Device information import + unit→contact linking (import_device_information.php)](features/device-information-import-and-contact-linking.md) | 1.0 | Prudential's **device-sync** cron (`worker/crons/toga2/prudential/import_device_information.php`) pulls device/asset records (from ServiceNow / the Dell CMDB fe | worker/crons/toga2/prudential/import_device_information.php, worker/crons/toga2/prudential/backfill_unit_contacts.php, dbchanges2/Client_Prudential/2026-07-07 - Contact Dedup Merge.sql |
 | [Prudential: OneUptime order-pipeline backlog monitors (Monitor/Prudential/*)](features/oneuptime-order-pipeline-monitors.md) | 2.0 | Three worker2 OneUptime push monitors (TRUE-80587) that watch the Prudential/Dell order pipeline for **stalls**, which were previously invisible — a stuck pipel | worker2/Worker/Monitor/Prudential.php, worker2/Config/production.ini, dbchanges2/Core/2026-08-07a - Prudential AIG ServiceNow OneUptime monitor crons.sql, dbchanges2/Client_Prudential/2026-04-08 - Insert Customers.sql |
-| [Prudential: order email PDF attachments (which guide goes on which email)](features/order-email-pdf-attachments.md) | 1.0 | Every customer-facing Prudential order email carries S3-hosted PDF guides, and **which** guide is attached is decided by the service request type. | worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php, worker/crons/toga2/prudential/transmissions_to_netsuite.php, worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php, worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php, worker/crons/toga2/prudential/test_new_hire_email.php |
+| [Prudential: order email PDF attachments (which guide goes on which email)](features/order-email-pdf-attachments.md) | 1.0 | Every customer-facing Prudential order email carries S3-hosted PDF guides, and **which** guide is attached is decided by the service request type. | worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php, worker/crons/toga2/prudential/transmissions_to_netsuite.php, worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php, worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php |
 | [Prudential: Service Request Regional Address Validation](features/service-request-address-validation.md) | 2.0 | The `prePost` interceptor on `_Model_Prudential_ServiceRequest` validates `deliverToAddress` fields differently depending on which Prudential regional customer | _underscore/Model/Prudential/ServiceRequest.php, _underscore/Test/Prudential/ServiceRequestTest.php |
 | [Prudential: Service Request rejection alert email](features/service-request-rejection-alert-email.md) | 2.0 | When a Prudential ServiceNow→TOGa service-request submission (`POST /v2/service-requests`) is **rejected by validation**, TOGa now sends a real-time internal al | worker2/Worker/Client/Prudential/reports/ReqRejectionEmail.php, _underscore/Model/Prudential/ServiceRequest.php |
 | [Prudential: Sales Orders CSV export (TOGa 2.5 Supply)](features/supply-orders-csv-export.md) | 2.0 | The **Export** button on the TOGa 2.5 Supply *Sales Orders* page is **Prudential-only**: it downloads a 22-column CSV (`prudential-orders-<YYYY-MM-DD>.csv`) cov | toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/PRUDENTIAL/exportApiFields.json, toga25-supply/src/pages/SalesOrders/api/prudentialExportApi.ts, toga25-supply/src/pages/SalesOrders/hooks/usePrudentialOrdersExport.ts, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx |

package/knowledge/clients/prudential/features/order-email-pdf-attachments.md

@@ -6,17 +6,17 @@ project: Worker
 client: prudential
 type: client-feature
 status: active
-updated: 2026-08-28
+updated: 2026-08-31
 owners: ["bala"]
 files:
   - worker/crons/toga2/prudential/generate_sales_and_purchase_orders_from_service_requests.php
   - worker/crons/toga2/prudential/transmissions_to_netsuite.php
   - worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php
   - worker/crons/toga2/prudential/transmit_closecomplete_updates_prudential.php
-  - worker/crons/toga2/prudential/test_new_hire_email.php
 related:
   - transmit-ordershipped-email.md
   - ../profile.md
+  - ../../../1.0/apps/library/features/email-test-mode-and-write-free-sends.md
 ---
 
 ## Summary
@@ -83,6 +83,64 @@ all three returned HTTP 200 (verified 2026-08-27). Two of them are **renamed on
 The Mac guide dominates: a new-hire email is roughly **11 MB** once base64-encoded. Grepping for
 the attached-as filename will not find the S3 object — search the S3 basename.
 
+## The verbiage has to match what actually attached
+
+Every attach is guarded by `if ($pdfGuideX !== false)`, but until 2026-08-31 the `$attachmentText`
+paragraph that *describes* the attachments was unconditional. A failed S3 fetch therefore produced
+an email whose copy pointed the recipient at guides that were not on the message — and it always
+said "guides" plural even when a single guide attached.
+
+The rule now, in every branch that was touched: **derive the sentence from the guards, not from
+the intent.**
+
+- Count (or list) the guides that actually attached.
+- Nothing attached → `$attachmentText = ''` and the paragraph disappears entirely.
+- One guide → "guide" / "is provided"; two → "guides" / "are provided"
+  (`$guideNoun`, `$guideVerb`).
+- Name only the devices whose guide attached, built from `$pdfGuide11` / `$pdfGuideMac` and joined
+  with `implode(' and ', $attachedGuideDevices)`.
+
+One subtlety in the Breakfix/Swap/Label order-created branch: that branch attaches the Windows 11
+guide **and** the return-instructions doc, but the sentence is a *getting started* sentence. It is
+therefore tied to `$pdfGuide11` alone — the return doc is not a getting started guide and must not
+make that sentence appear:
+
+```php
+$attachmentText = ($pdfGuide11 !== false ? 'When you do end up receiving equipment, you can refer to the attached guide for step-by-step instructions on getting started.' : '');
+```
+
+Fixed in four places (TRUE-81393, PR #1707, merged to `_production` 2026-08-31): the new-hire
+order-created branch, the Breakfix/Swap/Label order-created catch-all, and the new-hire **and**
+non-new-hire blocks in **both** shipped crons.
+
+## Email template anatomy (and the dead per-item rows)
+
+**The ordered items are never listed in these emails.** In each of the four crons, the
+`$data = $data . "<tr>…"` append that sits *inside* the `foreach (... as $item)` loop is wrapped in
+a `/* … */` comment. The loop still runs, and it still calls the Etilize/spexlive catalog API
+(`ws-na1.spexlive.net/service/rest/catalog`) to resolve a product thumbnail into `$url` — but
+nothing it produces reaches the message. Each body is only a header chunk plus a footer chunk. If
+you are asked "why doesn't the item show up in the email", this is why; if you are asked to add
+items back, the markup is already there, commented, and the thumbnail lookup already works.
+
+There are **8 distinct templates**, each roughly 150–300 lines of inline HTML:
+
+| Stage | Templates | Where |
+|---|---|---|
+| Order created | 4 — new hire, reclaim, refresh, Breakfix/Swap/Label catch-all | `generate_sales_and_purchase_orders_from_service_requests.php` |
+| Shipped | 2 — new hire, non-new-hire | duplicated **identically** in `transmissions_to_netsuite.php` and `transmit_ordershipped_updates_prudential.php` |
+| Delivered | 2 — new hire, non-new-hire | `transmit_closecomplete_updates_prudential.php` |
+
+Only the new-hire and Breakfix/Swap/Label order-created templates carry the (commented) item loop;
+the reclaim and refresh order-created branches have no item loop at all.
+
+Variables the templates interpolate — useful if you are reproducing one outside its cron:
+
+- **Order created** — fields off `$rowServiceRequest` (incl. `reqNumber`), plus `$state`,
+  `$salesOrderNumber` and `$attachmentText`.
+- **Shipped / delivered** — flat locals: `$name`, `$line1`, `$line2`, `$city`, `$state`, `$zip`,
+  `$orderNumber`, `$reqNumber`, `$trackingNumber` / `$trackingNumbers[$index]`, `$attachmentText`.
+
 ## How to change an attachment safely
 
 1. Every fetch goes through the file-scope `safeFetchPdf()` helper, never bare
@@ -100,24 +158,59 @@ the attached-as filename will not find the S3 object — search the S3 basename.
    precisely the type that most needs the return instructions. That guard is how Reclaim ended up
    receiving zero attachments.
 
-## Testing
-
-`crons/toga2/prudential/test_new_hire_email.php` (local, untracked) rebuilds the new-hire email
-verbatim — same subject, same HTML template, same S3 fetches — mails it to a hardcoded
-`$testRecipients` list, and prints each PDF's attached/missing state and byte size before
-sending. It **writes nothing**: no sales order, no purchase order, no api2 call, no SQL. It
-deliberately calls only `App_Framework_Worker::initialize()` and **not**
-`App_Framework::cronInitialization()`, because that INSERTs a `CronJobExecutions` row.
-
-Run it from the worker repo's `crons/` directory with the `library` and `_underscore` repos on
-the include path:
-
-```
-php -d include_path=".;<library>;<_underscore>" toga2/prudential/test_new_hire_email.php
-```
+## Testing these emails without writing anything
+
+**There is no committed test harness — do not go looking for one.** Three throwaway scripts
+(`test_new_hire_email.php`, `test_prudential_order_emails.php`,
+`test_prudential_email_templates.php`) were written under `crons/toga2/prudential/` on 2026-08-31
+to mail every stage/type combination with the real templates and the real S3 PDFs. They were
+**never committed and are no longer in the working tree**. What is durable is the technique.
+
+A harness that mails a real, byte-identical copy of one of these emails while writing **nothing**
+to the database needs all of this:
+
+- `setQueueForSending(false)`, `sendEmailEvenIfOutboundEmailIsDisabled = true`, and
+  `setIsLogEnabled(false)` on the `App_Email` object. All three — the first two keep it out of
+  `Common.EmailsQueued`, the third keeps it out of `Logs.Email`. Full detail in
+  [App_Email Side Effects & Test Mode](../../../1.0/apps/library/features/email-test-mode-and-write-free-sends.md).
+- `App_Framework_Worker::initialize()` **only**. Do **not** call
+  `App_Framework::cronInitialization()` — it INSERTs a `CronJobExecutions` row. Set
+  `set_time_limit()` and `date_default_timezone_set()` yourself instead.
+- One read-only SELECT for the sample data (below), rather than the cron's api2 fetches.
+- Print each PDF's resolved/missing state and byte size **before** sending; PHPMailer 5 will send
+  the message anyway if an attachment is unreadable.
+
+**Run it on the worker server if anyone other than you needs to receive it.** Local and beta
+configs have `internal.test_mode = 1`, which discards the recipient list and sends only to
+`email.dev_email_to`. `config.worker.ini` on the worker server has `test_mode = 0`.
+
+### Read-only query for a real sample request
+
+One row per request type is enough to exercise every template. Join `ServiceRequests` to
+`Addresses` on `deliverToAddressId`, `States` on `Addresses.stateId`, `Contacts` on
+`requestedForContactId`, and **LEFT JOIN** `SalesOrders` on `SalesOrders.serviceRequestId`
+(left, because an unprocessed request has no SO yet). Select
+`ServiceRequests.c_reqNumber AS reqNumber`, `Contacts.firstName`, the address parts,
+`States.code`, and `SalesOrders.number` — that is the exact set the shipped/delivered templates
+interpolate.
+
+All six request types have live rows in prod `Client_Prudential` (verified 2026-08-31); **Swap has
+only 2 rows**, the rest have thousands, so filter narrowly for Swap or you will miss it.
 
 ## Gotchas / known gaps
 
+- **`transmit_closecomplete_updates_prudential.php` still over-promises (~line 447).** Its
+  delivered email hardcodes "Guides for Windows 11 and MacBook devices are provided" with no
+  reference to whether either PDF actually attached — the exact bug fixed everywhere else on
+  2026-08-31. Left alone deliberately to keep PR #1707's diff to files already being changed.
+  **Worth a follow-up ticket.**
+- **`transmissions_to_netsuite.php` also sends *delivered* emails — with no attachments at all.**
+  It carries its own "New hire equipment has been delivered" / "Your equipment has been delivered"
+  blocks (~L1765 and ~L2149) that make **zero** `addAttachment()` calls, while
+  `transmit_closecomplete_updates_prudential.php` sends the **same two subjects** with the guides
+  attached. **Whether both fire for the same order was not established** — if they do, the
+  recipient gets a duplicate delivered email, one of them attachment-less. Check this before
+  changing either.
 - **`prudential_beta/` does not match prod.**
   `crons/toga2/prudential_beta/generate_sales_and_purchase_orders_from_service_requests.php` is
   `active: 1` on the same schedule but points at the beta DB and still references the retired
@@ -129,6 +222,16 @@ php -d include_path=".;<library>;<_underscore>" toga2/prudential/test_new_hire_e
   and was deliberately **not** touched.
 
 ## Change history
+- 2026-08-31 — CodeRabbit review follow-up (TRUE-81393, PR #1707, merged to `_production`): the
+  `$attachmentText` paragraph was unconditional while every attach was guarded, so a failed S3
+  fetch mailed copy referencing guides that were not attached, always pluralised. Now derived from
+  the guards in four places (new-hire and Breakfix/Swap/Label order-created branches, plus the
+  new-hire and non-new-hire blocks in both shipped crons), with the getting-started sentence tied
+  to the Windows 11 guide only. Also recorded: the per-item rows are commented out in all four
+  crons (items are never listed in any of these emails), the 8-template inventory, the
+  write-nothing test technique (the three throwaway harness scripts were never committed), and two
+  open items — the same over-promise still live in the delivered cron ~L447, and a second,
+  attachment-less delivered sender in `transmissions_to_netsuite.php` (bala)
 - 2026-08-27 — Client-reported: the new-hire order-created email attached the return-instructions
   PDF and carried no Mac guide. Swapped it to Win11 + Mac
   (`2026_Aug_PrudentialMacSetupGuide_ZCC.pdf` attached as `PrudentialMacSetupGuide.pdf`) and

package/knowledge/clients/prudential/features/transmit-ordershipped-email.md

@@ -6,7 +6,7 @@ project: Worker
 client: prudential
 type: client-feature
 status: active
-updated: 2026-08-28
+updated: 2026-08-31
 owners: ["rgirish", "bala"]
 files:
   - worker/crons/toga2/prudential/transmit_ordershipped_updates_prudential.php
@@ -93,6 +93,14 @@ same subjects, same branch shape — and also stamps `c_dtTransmittedOrderShippe
 It is easy to miss: it is not named like the other `transmit_*` crons. Any change to the shipped
 email's content or attachments must be applied to **both** files or the two senders drift.
 
+**And it does not stop at the shipped email — it also sends the two *delivered* emails.**
+`transmissions_to_netsuite.php` carries "Prudential: New hire equipment has been delivered"
+(~L1765) and "Prudential: Your equipment has been delivered" (~L2149), the **same two subjects**
+that `transmit_closecomplete_updates_prudential.php` sends — except the `transmissions_to_netsuite`
+versions make **no `addAttachment()` calls at all**. Whether both crons fire for the same order was
+not established (2026-08-31); if they do, the customer receives a duplicate delivered email, one
+copy of which is missing the guides. Establish this before touching either delivered path.
+
 It was also the last Prudential cron still calling `file_get_contents()` directly for its PDFs and
 calling `addAttachment()` unconditionally — so a failed S3 pull threw and killed the batch, and a
 false return would have mailed a 0-byte file under a real guide's name. Converted to
@@ -193,6 +201,16 @@ stamp (crash hits the next iteration). With multiple New-type POs, a crash on PO
 all subsequent POs in the same run.
 
 ## Change history
+- 2026-08-31 — TRUE-81393 / PR #1707 (merged to `_production`): the shipped email's
+  `$attachmentText` paragraph was unconditional while each attach was guarded, so a failed S3 pull
+  produced copy promising guides that were not attached — and it said "guides" even for a single
+  guide. Both blocks in this cron (new hire and non-new-hire) and both in
+  `transmissions_to_netsuite.php` now build the sentence from `$pdfGuide11`/`$pdfGuideMac`, naming
+  only what attached and dropping the paragraph when nothing did. Also discovered: the per-item
+  `<tr>` append inside the `foreach ($purchaseOrderItems as $item)` loop is **commented out** here
+  and in the sibling crons, so ordered items never appear in these emails (the loop still calls the
+  Etilize thumbnail API for nothing); and `transmissions_to_netsuite.php` additionally sends the
+  two **delivered** emails with no attachments. See order-email-pdf-attachments.md (bala)
 - 2026-08-27 — Extended the `safeFetchPdf()` + per-PDF-guard pattern to
   `transmissions_to_netsuite.php`, the last cron still fetching PDFs with bare
   `file_get_contents()` and attaching unconditionally. Also recorded that this cron is a **second

package/package.json

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