toga-ai 1.0.731 → 1.0.733

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

@@ -11,7 +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 |
+| [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/model/logs/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-test-mode-and-write-free-sends.md

@@ -6,10 +6,11 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-31
+updated: 2026-09-01
 owners: ["bala"]
 files:
   - library/app/email.php
+  - library/app/model/logs/email.php
   - library/app/framework.php
 related:
   - ./email-queue-attachments.md
@@ -32,7 +33,7 @@ Verified against `library/app/email.php` on 2026-08-31.
 
 | Write | When | How to suppress |
 |---|---|---|
-| `Logs.Email` row (`App_Model_Logs_Email`) | every **inline** send, success or failure | `setIsLogEnabled(false)` |
+| `Logs.Emails` 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):
@@ -46,6 +47,40 @@ if ($this->queueForSending || (!$this->sendEmailEvenIfOutboundEmailIsDisabled &&
 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.
 
+## Where the log lives — and how to verify a send actually happened
+
+The log row is the **only** durable proof that a 1.0 script really sent a mail, so knowing where
+it lands matters. `App_Model_Logs_Email` (`library/app/model/logs/email.php`) declares
+`TABLENAME = 'Emails'`, `DATABASE = 'db_logs'` and `$_databaseNameOverride = 'Logs'`. Read that
+literally:
+
+- **Table is `Emails` (plural), schema `Logs`**, and it lives in the **legacy (v1) environment** —
+  the one `db_logs` points at for the 1.0 tier.
+- It is **not** in the prod `Logs` schema, and **not** in a per-client `Logs_<Client>` schema.
+  Prod `Logs_Compass` has an `Email` (singular) table used by **2.0**, and it stays empty for
+  these 1.0 cron emails. Looking there is the usual wrong turn.
+
+Columns worth reading: `dtSent`, `isSuccess`, `error`, `sourceJob`, `instanceId`, `subject`,
+`from`, `to`, `cc`, `bcc`, `body`.
+
+```sql
+# legacy env, schema Logs
+SELECT id, dtSent, isSuccess, error, sourceJob, subject, `to`
+FROM Emails
+WHERE subject LIKE '<subject prefix>%'
+ORDER BY id DESC;
+```
+
+Two reading rules:
+
+- **A row exists only if the code reached `->send()` and took the inline branch.** No row means
+  either the job never got that far (e.g. it had nothing to report), or the message was queued
+  instead (see the table above), or logging was disabled. It does **not** by itself mean a
+  failure.
+- **`sourceJob` is `$_SERVER['SCRIPT_NAME']`, which tells you how it ran.** A full
+  `/var/www/html/crons/...` path is a scheduled run on the server; a bare filename is a manual
+  CLI run someone did by hand.
+
 ## 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
@@ -54,7 +89,7 @@ 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`.
+3. `setIsLogEnabled(false)` — do not insert into `Logs.Emails`.
 
 ## `App_Email` only ever *narrows* the recipient list
 
@@ -114,12 +149,16 @@ php -d include_path=".;<library>;<_underscore>" <path/to/script>.php
   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.
+  suppresses `Logs.Emails`; 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-09-01 — Corrected the log target: the table is **`Emails`** (plural) in schema **`Logs`**
+  on the **legacy** environment, not `Logs.Email` and not a per-client `Logs_<Client>` schema
+  (prod `Logs_Compass.Email` is the 2.0 table and stays empty for 1.0 cron mail). Added the
+  verification query and the `sourceJob` scheduled-vs-manual tell. (bala)
 - 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

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

@@ -3,7 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Worker (1.0 Framework) Architecture](architecture.md) | `worker` is the legacy (**1.0** `App_` framework) **background-job tier**. | worker/index.php, worker/_/app/framework.php, worker/crons/, worker/schedules/, worker/ebs/cron.worker.php, worker/.ebextensions/035_cron.worker.config, worker/crons/infrastructure/execute_dbchanges.php, worker/.ebextensions/030_dbchanges.config |
-| [Compass MA Sales Order Exception Report](features/compass-ma-sales-order-exception-report.md) | A worker cron that emails operations the "Compass Refresh Exception Report" — Compass `MA%` sales orders whose corresponding Office Depot (ODP) sales order has | worker/crons/toga2/compass/workflow/7_generate_ma_sales_order_exception_report.php |
+| [Compass MA Sales Order Exception Report](features/compass-ma-sales-order-exception-report.md) | A worker cron that emails operations the "Compass Refresh Exception Report" — Compass `MA%` sales orders whose corresponding Office Depot (ODP) sales order has | worker/crons/toga2/compass/workflow/7_generate_ma_sales_order_exception_report.php, worker/schedules/cron.worker.sync.json |
 | [Compass Manager Approval Reminder Emails (1.0 worker crons)](features/compass-manager-approval-reminder-emails.md) | Two 1.0 worker crons nag approvers about sales orders still waiting on a decision — one per Compass tenant. | worker/crons/toga2/compass/compass_email_reminders.php, worker/crons/toga2/compasscanada/compass_email_reminders.php, worker/schedules/cron.worker.sync.json, worker1.5/crons/toga2/compass/compass_email_reminders.php, worker1.5/schedules/cron.worker.json |
 | [Compass Partial In-Transit & Delivered Emails (per package)](features/compass-partial-in-transit-delivered-emails.md) | Compass USA and Compass Canada send a **per-package** in-transit email (and a matching delivered email) instead of one email listing the whole order. | worker/crons/toga2/compass/update_salesorder_status_from_odp.php, worker/crons/toga2/compass/send_delivered_email.php, worker/crons/toga2/compasscanada/update_salesorder_status_from_odp.php, worker/crons/toga2/compasscanada/workflow/3_update_salesorder_status_from_grand_and_toy.php, worker/crons/toga2/compasscanada/send_delivered_email.php, worker/crons/toga2/compasscanada/workflow/test_partial_in_transit_email.php, worker/crons/toga2/compasscanada/workflow/test_partial_delivered_email.php, library/app/client/compasscanada.php |
 | [Elite TOGA 2.0 → TOGaDeskSupport Standalone Attachment Sync](features/elite-togadesk-attachment-sync.md) | `sync_togadesk_elite_attachments.php` is a standalone cron (every 5 minutes) that syncs file attachments from TOGA 2.0 into TOGaDeskSupport for Elite. | worker/crons/toga2/elite/sync_togadesk_elite_attachments.php, worker/crons/toga2/elite/test_sync_togadesk_elite_attachments.php |
@@ -19,4 +19,4 @@
 | [isFulfillable Multi-Client Backfill (all togasupply clients)](workflows/isfulfillable-multi-client-backfill.md) | One-time backfill that catches up `Items.isFulfillable` on **existing** items across **all 17 togasupply clients** (AIG, Broward Sheriff, Canon, Endeavor Health | worker/crons/toga2/netsuite/backfill_isfulfillable_all_clients.php, library/app/api/toga2.php |
 | [Deduplicating NetSuite duplicate Items across client DBs (recursive MERGE)](workflows/netsuite-duplicate-items-dedup.md) | A one-time, per-client data cleanup that collapses **duplicate `Items` rows sharing a `partNumber`** in each NetSuite → TOGa Supply client DB down to a single c | library/app/api/toga2.php, worker/crons/toga2/netsuite/common_sync_togasupply.php |
 | [Onboarding a Client to the NetSuite TOGa Supply Sync](workflows/onboarding-client-to-netsuite-togasupply-sync.md) | How to add a new TOGa 2 client to the per-client NetSuite → TOGa Supply importer (`worker/crons/toga2/netsuite/`). | worker/crons/toga2/netsuite/sync_togasupply.php, worker/crons/toga2/netsuite/common_sync_togasupply.php, worker/crons/toga2/netsuite/sync_togasupply_elite.php, worker/schedules/cron.worker.sync.json, dbchanges2/_modules/netsuite/2026-04-01 - Parameters.sql, dbchanges2/_modules/netsuite/2026-08-05 - CLEAN NETSUITE CLINET.SQL |
-| [Tracing a 1.0 worker cron run in production (no stdout, silent skips)](workflows/tracing-a-worker-cron-run-in-production.md) | How to answer *"did this cron actually run, and what did it do?"* on the 1.0 `worker` tier, where **there is no usable stdout** and **a skipped run leaves no tr | worker/ebs/cron.worker.php, worker/schedules/cron.worker.sync.json, worker/schedules/cron.worker.infrastructure.json, worker/.ebextensions/009_setup_phpini.config, library/app/framework.php |
+| [Tracing a 1.0 worker cron run in production (no stdout, silent skips)](workflows/tracing-a-worker-cron-run-in-production.md) | How to answer *"did this cron actually run, and what did it do?"* on the 1.0 `worker` tier, where **there is no usable stdout** and **a skipped run leaves no tr | worker/ebs/cron.worker.php, worker/schedules/cron.worker.sync.json, worker/schedules/cron.worker.infrastructure.json, worker/.ebextensions/009_setup_phpini.config, library/app/framework.php, library/app/email.php, library/app/model/logs/email.php |

package/knowledge/1.0/apps/worker/features/compass-ma-sales-order-exception-report.md

@@ -6,11 +6,14 @@ project: Worker
 client: compass-usa
 type: feature
 status: active
-updated: 2026-08-21
+updated: 2026-09-01
 owners: ["bala", "mhammontree"]
 files:
   - worker/crons/toga2/compass/workflow/7_generate_ma_sales_order_exception_report.php
-related: []
+  - worker/schedules/cron.worker.sync.json
+related:
+  - ../workflows/tracing-a-worker-cron-run-in-production.md
+  - ../../library/features/email-test-mode-and-write-free-sends.md
 ---
 
 ## Summary
@@ -22,6 +25,9 @@ but haven't. Runs against the Compass client DB (`db_prod_compass` / `Client_Com
 ## Key files / entry points
 - `worker/crons/toga2/compass/workflow/7_generate_ma_sales_order_exception_report.php` — the
   whole job: one main SELECT, a per-row NetSuite recheck, and a PhpSpreadsheet Excel email.
+- `worker/schedules/cron.worker.sync.json` — the schedule entry
+  **"Exception Report - EDI Office Depot (8am - 4pm)"**, `0 8-14 * * *` (hourly, on the hour;
+  the crontab runs **Central** time).
 
 ## How it works
 1. **Main query** walks a two-hop bridge chain to connect the customer order to the vendor order:
@@ -37,7 +43,9 @@ but haven't. Runs against the Compass client DB (`db_prod_compass` / `Client_Com
    (`CUSTOMER_ID__AGILANT` = 3) sales order tied to that ODP PO number. If found → it back-fills
    `c_netsuiteInternalSalesOrderId` on the ODP SO and skips the row (drops it off the report
    permanently). If not found → it writes the row to the Excel.
-4. Emails the workbook to operations only if at least one data row was written.
+4. Emails the workbook to operations **only if at least one data row was written** — the send is
+   guarded by `if ($rowNumber > 2)`, where row 1 is the header. Subject is
+   `Compass Refresh Exception Report : <date>`.
 
 ## Data model
 - `Client_Compass.SalesOrders` — the ODP sales order is the one keyed on (`id AS salesOrderId`,
@@ -69,10 +77,19 @@ Compass USA only — this is a Compass-specific integration cron.
 - **Don't fake the NetSuite id to hide an order.** Writing a bogus `c_netsuiteInternalSalesOrderId`
   removes it from the report but corrupts the field for anyone who reads it later. Use the stage
   lever instead.
+- **A silent hour is not a failure.** Because of the `$rowNumber > 2` guard, an hour with zero
+  exceptions sends nothing at all. Before treating a missing report as a broken cron, check the
+  run itself (`Common.CronJobExecutions`) and the send log — the legacy env's `Logs.Emails`
+  (schema `Logs`), `WHERE subject LIKE 'Compass Refresh Exception Report%'`. See
+  [Tracing a 1.0 worker cron run](../workflows/tracing-a-worker-cron-run-in-production.md).
 - `$inProduction = true` switches the DB link to `db_prod_compass`; set false to test against
   `db_beta_compass`.
 
 ## Change history
+- 2026-09-01 — Recorded the schedule (`cron.worker.sync.json`, "Exception Report - EDI Office
+  Depot (8am - 4pm)", `0 8-14 * * *`) and the `$rowNumber > 2` send guard, so a silent hour reads
+  as "zero exceptions", not a fault; added how to prove a send via the legacy `Logs.Emails` table.
+  Verified 2026-09-01: recent runs all logged `isSuccess = 1`. (bala)
 - 2026-08-21 — Removed the departing employee `mreich@togatech.com` from this cron's hardcoded
   recipient list (TRUE-80451). Recipients are in-script, not DB-driven. (mhammontree)
 - 2026-06-18 — Added stage-based exclusion so orders closed/canceled on ODP's end drop off the

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

@@ -530,6 +530,20 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
   a new line is actually created. Full root cause, the prod cleanup migration, and the
   deploy-fix-before-cleanup sequencing live in the
   [Compass ODP Duplicate PO-Line Cleanup](../../../clients/compass-usa/workflows/odp-duplicate-po-line-cleanup.md).
+- **Customer-PO created from a sales order was missing `dateOrder` and had `cost` hardcoded 0 (both
+  fixed 2026-09-01, shared, `library` only).** In `syncSalesOrderFromNetsuite`
+  (`library/app/api/toga2.php`), the "create the customer PO" `POST /purchase-orders` branch
+  (~L1961) never set `dateOrder`, so every customer PO built from a sales order had
+  `PurchaseOrders.dateOrder` NULL. Fix: add
+  `'dateOrder' => App_Date::convertToTimezone($nsOrder->tranDate, 'Y-m-d', 'America/New_York')`
+  (the same expression that sets the SO's own `dateOrder` at ~L1394). Separately, all **three**
+  PO-item creation sites (`POST /purchase-order-item-sales-order-items`, ~L1863/1937/2051) sent
+  `'cost' => 0`; because this PO is the customer PO **for** the sales order, the PO line's cost is
+  the SO line's price — changed to `'cost' => $salesOrderItem['price']` (`$itemPrice`, from the
+  NetSuite rate or amount/qty fallback built ~L1223, always present). **Both are INSERT-ONLY:** the
+  create branches run only when the PO / line does not already exist and nothing PUTs `dateOrder` or
+  `cost`, so re-syncs and a second SO sharing the same customer-PO number never overwrite them.
+  **Existing NULL/`cost=0` rows are NOT backfilled** — new records only.
 - **⚠ A single un-deletable renumbered line could freeze the entire SALES_ORDERS section (fixed
   2026-08-17).** When NetSuite renumbers a line, `syncSalesOrderFromNetsuite` renumbers by
   **DELETE `/sales-order-items/{uuid}` then re-create in the per-item loop**. Its "pinned row" guard
@@ -881,9 +895,43 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
   `'catalog' => ['name' => 'Agilant']` on the inventory-adjustment item-create. Stops all new duplicates.
   The one-time cleanup of the accumulated ~4,300 duplicate part numbers across all 17 clients is the
   [NetSuite duplicate-Items dedup workflow](../workflows/netsuite-duplicate-items-dedup.md).
+- **⚠ Inventory-adjustment `/units` reconciliation missed an existing unit on a serial-CASE mismatch →
+  1062 dup-key freeze (fixed 2026-09-01, shared, `library` only).** In
+  `syncInventoryAdjustmentFromNetsuite` (`library/app/api/toga2.php` ~L5985) the PHP lookup of existing
+  units was keyed by the **returned** unit serial (`$thisLookupUnitsBySerialNumber[$unit->serialNumber]`,
+  stored `'n/a'`) but looked up with the NetSuite serial **uppercased** via `strtoupper` (`'N/A'`). **PHP
+  array keys are case-sensitive; the `Units.itemId_serialNumber` unique key is case-insensitive** — so
+  the existing unit was missed, re-INSERTed, and collided MySQL **1062** ("Duplicate entry '560-N/A'")
+  → `EV-10` → the section aborted (fail-loud, no per-record try/catch) and froze at `1-RUNNING`. **Fix:**
+  key the lookup by `strtoupper($unit->serialNumber)` so it matches the uppercased NetSuite serial;
+  section self-heals on deploy (mode→IDLE, watermark advances). The `Items.uuid=$uuidItem` scoping was
+  left intact deliberately — copying the fulfillment "serial-only" lookup would be wrong for the shared
+  `'N/A'` placeholder serial (it would reuse another item's placeholder unit). **Durable lesson: when a
+  PHP lookup mirrors a case-insensitive DB unique key, normalize the KEY the same way you normalize the
+  probe — case-fold both, not one.**
+- **Diagnosis playbook (durable) — localize a frozen inventory-adjustment section without NetSuite
+  access.** The 2026-09-01 NYCHH freeze above was diagnosed purely from DB logs, and item-matching was
+  *ruled out* (item 560 / partNumber B11B242201 is the only Agilant-catalog item for that part — no
+  duplicate second-catalog item, `$uuidItem` resolved correctly; the inventory-adjustment item-create
+  already stamps catalog `Agilant`). Chain: **`Client_<Id>.Parameters`** (localize the stuck section:
+  `1-RUNNING` + frozen watermark) → **`Logs.Event` filtered by `clientId`** (crash `file:line`, the
+  chain `toga2.php → common_sync_togasupply.php → sync*FromNetsuite`, plus the `transactionId`) →
+  **`Logs_<Client>.Api` on that `transactionId`** (the untruncated `EV-*`/MySQL rejection + payload).
+  A "silent freeze" here is a serial/data collision, not necessarily a catalog/item-matching problem —
+  read the untruncated Api-log rejection before assuming item matching.
 
 ## Change history
 
+- 2026-09-01 — **Customer-PO `dateOrder`/`cost` fixes + NYCHH inventory-adjustment serial-case unfreeze
+  (shared, `library` only, working-tree — not yet committed/deployed).** `syncSalesOrderFromNetsuite`
+  now sets the customer PO's `dateOrder` from the SO `tranDate` (was always NULL) and its PO lines'
+  `cost` from the SO line `price` (was hardcoded 0) across all three PO-item create sites — both
+  INSERT-only, no backfill of existing rows. `syncInventoryAdjustmentFromNetsuite` now keys the `/units`
+  reconciliation lookup by `strtoupper($unit->serialNumber)` so a case-mismatched serial (`'n/a'` vs
+  `'N/A'`) matches the case-insensitive `Units.itemId_serialNumber` unique key — was missing the
+  existing unit and 1062-colliding, freezing NYCHH `INVENTORY_ADJUSTMENTS` at `1-RUNNING` (watermark
+  frozen 2022-12-28). Ruled out item-matching as the cause (single Agilant-catalog item, `$uuidItem`
+  correct). All three benefit every togasupply client. (jcardinal)
 - 2026-09-01 — **TRUE-81576: stopped runaway duplicate `ShippingCarriers` creation (worker + library).**
   `common_sync_togasupply.php` now seeds the carrier lookup from its own paged `GET /shipping-carriers`
   loop instead of harvesting carriers out of the `/shipping-methods` loop — a carrier with zero

package/knowledge/1.0/apps/worker/workflows/tracing-a-worker-cron-run-in-production.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: workflow
 status: active
-updated: 2026-08-28
+updated: 2026-09-01
 owners: ["bala", "kyalamarthi"]
 files:
   - worker/ebs/cron.worker.php
@@ -14,11 +14,14 @@ files:
   - worker/schedules/cron.worker.infrastructure.json
   - worker/.ebextensions/009_setup_phpini.config
   - library/app/framework.php
+  - library/app/email.php
+  - library/app/model/logs/email.php
 related:
   - ../architecture.md
   - ./diagnosing-frozen-cron-checkins.md
   - ../features/forecast2-supporting-records-import.md
   - ../../library/features/cron-execution-monitoring.md
+  - ../../library/features/email-test-mode-and-write-free-sends.md
   - ../../../1.0/standards/backend-php.md
 ---
 
@@ -119,6 +122,31 @@ each PO then costing roughly 40 seconds — comfortably past a 5-minute schedule
 skips while processing are still listed, so accumulated `SENT/` and `OUTBOX/` objects inflate
 every run.
 
+## Step 6 — if the cron's job is to email, check the email log, not the inbox
+"Did the report actually go out?" is answered by the **legacy** environment's `Logs.Emails` table
+(schema `Logs`, table `Emails` — plural). `App_Email::send()` writes one row per **inline** send,
+success or failure. It is **not** in the prod `Logs` schema and **not** in `Logs_<Client>`; a
+prod `Logs_Compass.Email` table exists but is the 2.0 one and stays empty for 1.0 cron mail.
+
+```sql
+# legacy env, schema Logs
+SELECT id, dtSent, isSuccess, error, sourceJob, subject, `to`
+FROM Emails
+WHERE subject LIKE '<subject prefix>%'
+ORDER BY id DESC;
+```
+
+- `isSuccess = 0` with `error` populated → the send was attempted and failed; that is a real fault.
+- **No row is not automatically a fault.** Most reporting crons only call `->send()` when they have
+  something to report, so a silent slot usually means "nothing to report". Confirm the run itself
+  happened via Step 4's `CronJobExecutions` row before calling it a failure.
+- `sourceJob` is `$_SERVER['SCRIPT_NAME']`: a full `/var/www/html/crons/...` path means a
+  **scheduled** server run, a bare filename means someone ran it **by hand**.
+
+Detail on what else `send()` writes (the `Common.EmailsQueued` branch, `setIsLogEnabled(false)`,
+`test_mode` recipient rewriting) is in
+[App_Email Side Effects & Test Mode](../../library/features/email-test-mode-and-write-free-sends.md).
+
 ## Deploy-time trap: a PHP 8-only syntax kills the whole cron with no visible error
 This tier runs **PHP 7.2**, so a **PHP 8 named argument** (`someFunction(items: $x)`) is a
 **parse error**, not a runtime warning:
@@ -143,6 +171,10 @@ to **2.0 only**. The 1.0 standard wins in `library/`, `worker/` and every other
 signal, it is a latent bug.
 
 ## Change history
+- 2026-09-01 — Added **Step 6: check the email log, not the inbox** — a 1.0 cron's sends land in
+  the **legacy** env's `Logs.Emails` (schema `Logs`, table `Emails`), never prod `Logs` or
+  `Logs_<Client>`; gave the verification query, and noted that a missing row usually means the job
+  had nothing to report and that `sourceJob` distinguishes a scheduled run from a manual one. (bala)
 - 2026-08-28 — Added **"which of the 7 boxes runs it — and in which timezone"** to Step 1, after a
   production trace of the Forecast2 supporting-records cron (TRUE-81213). A `cron.worker.<role>.json`
   job runs on exactly one dynamically-assigned instance: find it via `Vision_Log.Workers` or the EC2

package/knowledge/2.0/apps/api2/features/environment-variable-drives-underscore-branch.md

@@ -6,7 +6,7 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-08-31
+updated: 2026-09-01
 owners: ["bala", "mhammontree", "apeterson", "jcardinal", "tcox"]
 files:
   - api2/.ebextensions/git.php
@@ -22,6 +22,8 @@ related:
   - ../workflows/environment-configuration-and-provisioning.md
   - ../workflows/codepipeline-codeconnections-deploy.md
   - ../../_underscore/features/togaiq-gateway-client.md
+  - ./request-logging.md
+  - ./v2-deadlock-retry.md
   - ../../dbchanges2/workflows/framework-branch-ahead-of-schema.md
 ---
 
@@ -176,6 +178,46 @@ patched) on `TableViewFields.isGroupable`.
 the tier trades a stale-code bug for a total outage. Full procedure:
 [framework branch ahead of schema](../../dbchanges2/workflows/framework-branch-ahead-of-schema.md).
 
+## ⚠ Never use a RECENTLY-ADDED `_underscore` symbol from api2 without checking branch containment
+
+The cross-repo ordering gotcha below says "land `_underscore` before deploying api2." That is
+necessary but **not sufficient**, because every environment pins its **own** `_underscore` branch
+(see the whole doc above). A framework symbol merged to `_production` may be **absent from `_beta`
+and `_sandbox-dev` for weeks**, so app code that references it is fine on prod and **fatal on the
+sandboxes**.
+
+**Concrete (2026-09-01, `TRUE-81056`).** The first version of the duplicate-`transactionId` log fix
+used `\_Database::ERRNO_DUPLICATE_ENTRY` inside a `catch` block. That constant was added by
+`_underscore` commit **`6355d0f0`** and, verified with `git show <branch>:Database.php`:
+
+| `_underscore` branch | `ERRNO_DUPLICATE_ENTRY` |
+|---|---|
+| `_production` | present |
+| `_sandbox-client` | present |
+| `_beta` | **absent** |
+| `_sandbox-dev` | **absent** |
+
+So on `api.beta.togahub.com` and `api.dev.sandbox.togahub.com` the code fataled with **`Undefined
+constant _Database::ERRNO_DUPLICATE_ENTRY`** — *thrown from inside the catch block*, which means the
+**real** error was replaced by a confusing one about the error handler. Confirmed live in
+`Logs.Event` **7405** (beta) and **7404** (dev-sandbox).
+
+**Hardening applied:** api2 now defines its own `MYSQL_ERRNO_DUPLICATE_ENTRY = 1062` and reads
+`\_Database::$lastErrorNumber` through `property_exists()`, so an older framework **degrades
+gracefully instead of fataling**.
+
+**The rule, for any app repo (api2, worker2) calling into `_underscore`:**
+
+- Before using a framework constant/method/property you (or a teammate) added recently, run
+  **`git branch -a --contains <commit>`** in `_underscore` and confirm it is on the branch of
+  **every** tier this code will run on — not just `_production`.
+- When the symbol is not everywhere yet, either **wait for it to land on all tiers**, or **guard the
+  reference** (`property_exists()` / `defined()` / a local constant) so an older framework falls back
+  rather than fatals.
+- **Never reference a not-yet-universal symbol from inside a `catch`/error path.** That is the worst
+  place for it: the fatal masks the very error you were trying to handle, and the incident is then
+  diagnosed against the wrong symptom.
+
 ## Gotchas / known issues
 
 - **⚠ Cross-repo change ordering: land `_underscore` BEFORE deploying api2.** Because api2's EB
@@ -269,7 +311,15 @@ the tier trades a stale-code bug for a total outage. Full procedure:
   documented in both places so a rotation updates both.
 
 ## Change history
-
+- 2026-09-01 — Added the rule that **api2 must not reference a recently-added `_underscore` symbol
+  without checking branch containment**, since each tier pins its own framework branch. Concrete
+  (`TRUE-81056`): `\_Database::ERRNO_DUPLICATE_ENTRY` (added by `_underscore` `6355d0f0`) is present
+  only on `_production` and `_sandbox-client`, so referencing it in a `catch` block fataled with
+  `Undefined constant` on beta and dev-sandbox (`Logs.Event` 7405 / 7404) — and because the fatal was
+  *inside the catch*, it replaced the real error with a confusing one. Hardened api2 to define its own
+  `MYSQL_ERRNO_DUPLICATE_ENTRY = 1062` and read `\_Database::$lastErrorNumber` via `property_exists()`.
+  Rule: run `git branch -a --contains <commit>` on `_underscore` before using a new framework symbol,
+  and never reference a not-yet-universal symbol from an error path. (bala)
 - 2026-08-31 — Recorded a **worked instance** of the cross-repo ordering rule: **`client-sandbox`
   went entirely down** — every request 500'd with `Call to undefined method
   _Model_Core_AclFieldPermission::resolveFieldPermissions()`. `api2@_sandbox-client` (`V2.php:6198`,

package/knowledge/2.0/apps/api2/features/request-logging.md

@@ -17,6 +17,8 @@ related:
   - ../architecture.md
   - ./api-payload-interceptors.md
   - ./v2-api-error-codes.md
+  - ./v2-deadlock-retry.md
+  - ./environment-variable-drives-underscore-branch.md
   - ../../_underscore/features/error-reporting-issue-event.md
   - ../../../../clients/aig/features/entitlement-intake.md
   - ../../../../clients/compass-usa/features/mits-po-to-so-item-linking.md
@@ -149,6 +151,116 @@ transaction no matter how many times apiproxy retried. That is why the retry att
 there even in principle — the two logs are not two views of the same rows. Join the two by
 `transactionId` when you need the full attempt sequence for one user action.
 
+## ⚠ A duplicate `transactionId` must NOT fail the request — save the row, then rename on 1062
+
+`Logs_<Client>.Api.transactionId` (and core `Logs.Api.transactionId`) carries a **UNIQUE** key, so
+the log-save at the end of `execute()` is the one place where **two copies of the same request
+collide**. Until 2026-09-01 that collision **turned an already-successful API response into an
+HTTP 500** — the response was fully built, the work was done, and the *audit row* killed it.
+
+**The old code was a check-then-insert** (`V2.php` ~L2283-2295 on `_production`):
+
+```php
+// PRE-FIX — structurally cannot work under concurrency
+$existingLog = new $logsApiModelName();
+$existingLog->transactionId = $transactionId;
+if ($existingLog->load()) {
+    $transactionId .= ('-' . (new \DateTime())->format('Y-m-d H:i:s.v'));
+    $log->transactionId = $transactionId;
+}
+$log->save();
+```
+
+**Why the pre-check can never work.** The rival copy's row is still inside its **uncommitted
+transaction**, so it is invisible to any `SELECT`. Both copies pass the check, both believe the id
+is free, and the second `INSERT` hits the unique key with **MySQL 1062**. The exception escapes the
+logger, unwinds to `Controller/Index.php`, and the caller gets a 500 for work that had already
+succeeded. **No lookup can fix this** — a read cannot see a row that has not been committed yet.
+
+**The fix (2026-09-01, `TRUE-81056` / commit `db94a26`)** — `saveApiLogUnderItsOwnTransactionId()`
+and `buildResendTransactionId()` in `V2.php`: **save first, and let the database arbitrate.** On a
+1062, rename the row to `<transactionId>-1`, then `-2`, and retry. Anything that is *not* a 1062 is
+logged with `error_log()` and swallowed — **a log row must never be the reason a finished request
+fails.** Properties worth knowing:
+
+- The suffix is always built from the **originally requested** id, so the third copy is `-2`, never
+  `-1-2`. Every copy of one user action still sorts and searches together.
+- The prefix is truncated to `TRANSACTION_ID_MAX_LENGTH` (255) minus the suffix, because a silent
+  MySQL column-width chop would re-collide.
+- The loop is **deliberately unbounded and cannot spin**: every UNIQUE column changes per attempt
+  (`_Model` mints a fresh `uuid` inside each `save()`, `id` is auto-increment, the resend number only
+  climbs), so each try eliminates one taken value and never re-asks for the same one.
+- **It also removes one `SELECT` per API request** against an ~11.5M-row table.
+
+### The duplicate comes from BELOW the application — you cannot stop it, only tolerate it
+
+Do not chase this as a double-click. The frontend axios interceptor
+(`toga2-commerce/src/api/axiosInstance.ts`) mints a **fresh uuid per request**, so a genuine
+double-click produces **two different ids**. Two requests sharing one id means the **identical bytes
+were replayed by something under the app**:
+
+- **2026-08-18 (production)** — the two copies arrived through **two different Zscaler proxy nodes**
+  (`136.226.49.71` and `136.226.49.80`) with **different ALB trace ids**.
+- **2026-08-28** — the copies came over a plain path with **no proxy hop at all**.
+
+A `GET` is safe to repeat, so browsers, corporate proxies and load balancers resend it on their own
+when a connection drops — and they resend the original bytes, `transactionId` included. This is the
+same mechanism already documented above for apiproxy's cross-region 5xx retry. **The server must
+tolerate the repeat; the client cannot prevent it.**
+
+### An UNAUTHENTICATED request still writes a log row — so the 500 was reachable with no token
+
+A **401 response still reaches the log-save code** and writes a row carrying the caller's
+`transactionId`. That is how the defect was proven from outside with no credentials, and it made the
+500 a (minor) unauthenticated abuse vector. The fix closes it. When reproducing any log-write
+behavior, remember you do **not** need a valid token to create a row.
+
+### ⚠ Accepted exposure — removing the 500 also removed an ACCIDENTAL write-rollback
+
+Recorded deliberately, because it is not obvious. On an uncaught `Throwable`,
+`Controller/Index.php` (~L308) rolls back the request's data changes. The 1062 escaping the logger
+was therefore **silently cancelling the losing duplicate's writes**. With the fix the loser no longer
+throws, so **two concurrent duplicate POSTs would both commit.**
+
+The intended guard is the **EV-5 client-`transactionId` replay check** (`V2.php` ~L1971-1977), but it
+is a `load()` on `Logs_Client_Api.transactionId` and therefore has **exactly the same
+uncommitted-read blind spot** as the code that was just removed — under true concurrency it does not
+see the rival either. Every recorded occurrence of this defect has been a **GET**, so nothing has
+been hit.
+
+**Status: known, accepted exposure — not a regression to revert.** The correct long-term fix is to
+**claim the `transactionId` at the START of the request instead of the end**, so the UNIQUE key
+enforces idempotency atomically and the loser is rejected before it does any work.
+
+### This is the fourth symptom of one root pattern — check-then-insert on `Logs.Api`
+
+Treat any new `Logs.Api` incident as a member of this family before theorizing:
+
+| Record | Symptom | What was done |
+|---|---|---|
+| `Logs.Issue 26` | Same defect on `/v2/users/me`, **312 occurrences** | "Fixed" 2026-08-25 (`84fd7a1`) by changing only the **fallback value** to a uuid — the race was left intact |
+| `Logs.Issue 250` | The surviving `/v2/users` case | Same root cause |
+| `Logs.Issue 2L` | Memory exhaustion on `/v2/auth/public` | `36ef31f` — the same pre-check full-table-scanned on a null/empty `transactionId` |
+| `Logs.Issue CT` | 500 on a successful request (this one) | `db94a26` — pre-check removed entirely |
+
+The 2026-08-25 work uuid'd the **auto-generated** log-row id, which is why the architecture doc's
+gotcha reads "FIXED". It did not touch the **client-supplied** id, which still went through
+check-then-insert. Both halves had to go.
+
+### Verifying a concurrency fix — confirm the CONSTRAINT exists in the target environment
+
+`Logs.Api.transactionId` is **UNIQUE on production, `sandbox-client` and `dev-sandbox`, but only a
+NON-unique index locally.** A local pass therefore proves nothing: the race cannot fail where the
+key does not exist. **Confirm the constraint in the environment you are testing before you trust a
+green result.**
+
+The method that worked:
+
+1. **Reproduced on production first try** with two concurrent unauthenticated `curl`s sharing one
+   `transactionId`.
+2. **Proven on `client-sandbox`**: three concurrent copies of the original failing request all
+   returned 401, wrote rows `<id>`, `<id>-1`, `<id>-2`, and produced **zero 500s**.
+
 ## Getting the REAL error behind a generic `EO-1` 500 (the three-hop chain)
 
 A 500 whose only content is `EO-1` — *"Operation Failed: An internal server error occurred"* —
@@ -288,7 +400,27 @@ re-send.
 > replay operationally, not by pasting payloads into the KB.
 
 ## Change history
-
+- 2026-09-01 — **Fixed the duplicate-`transactionId` 500** (`Logs.Issue CT`, `TRUE-81056` /
+  `db94a26`): the log-save at the end of `execute()` did a **check-then-insert**, which cannot work
+  under concurrency because the rival copy's row is still uncommitted and therefore invisible to the
+  `SELECT` — both copies passed, the second `INSERT` hit the UNIQUE key with **1062**, and the
+  exception turned an **already-successful response into a 500**. Replaced with
+  `saveApiLogUnderItsOwnTransactionId()` / `buildResendTransactionId()`: save first, and on 1062
+  rename to `<id>-1`, `-2` and retry, so the database arbitrates; any non-1062 error is `error_log`'d
+  and swallowed (a log row must never fail a finished request). Also drops one `SELECT` per request
+  against an ~11.5M-row table. Recorded that the duplicate originates **below the app** — the
+  toga2-commerce axios interceptor mints a fresh uuid per request, so a double-click yields two
+  *different* ids; the 2026-08-18 production pair arrived via two Zscaler nodes
+  (`136.226.49.71`/`.80`) with different ALB trace ids, the 2026-08-28 pair with no proxy hop — a GET
+  is safe to repeat, so proxies and load balancers resend the original bytes on their own. Recorded
+  that a **401 still writes a log row**, which made the 500 reachable unauthenticated. **Accepted a
+  known exposure**: the 500 was accidentally triggering the `Controller/Index.php` (~L308)
+  `Throwable` rollback of the loser's writes, and the EV-5 replay guard (`V2.php` ~L1971-1977) shares
+  the same uncommitted-read blind spot — every recorded case is a GET, and the real fix is to claim
+  the `transactionId` at the **start** of the request. Linked the family (`Logs.Issue` 26 / 250 / 2L)
+  and the verification rule: `Logs.Api.transactionId` is UNIQUE on prod/`sandbox-client`/`dev-sandbox`
+  but **non-unique locally**, so confirm the constraint before trusting a green test. Reported by
+  Compass Group; the defect is platform-wide. (bala)
 - 2026-09-01 — Added **Getting the REAL error behind a generic `EO-1` 500** — the three-hop chain
   from an opaque 500 to the actual failing field. Key new fact: `internalApiRequest()` logs each
   **nested** sub-request into `Logs_<Client>.Api` under a **randomly generated `transactionId`**

package/knowledge/2.0/apps/api2/features/v2-deadlock-retry.md

@@ -6,8 +6,8 @@ project: API
 client: shared
 type: feature
 status: draft
-updated: 2026-08-28
-owners: [jcardinal]
+updated: 2026-09-01
+owners: [jcardinal, bala]
 files:
   - api2/Controller/Index.php
   - api2/Component/Api/V2/V2.php
@@ -19,6 +19,8 @@ related:
   - ../../../../clients/compass-usa/features/asn-to-item-fulfillment.md
   - ../architecture.md
   - ./v2-api-error-codes.md
+  - ./request-logging.md
+  - ./environment-variable-drives-underscore-branch.md
 ---
 
 ## Summary
@@ -136,6 +138,22 @@ replay-safe and must stay off the list:
 idempotent or transaction-scoped, with no irreversible side effect and no consumed/mutated
 superglobal. Default is to leave a route off the list.
 
+## ⚠ `_Database::ERRNO_DUPLICATE_ENTRY` has SHIPPED — but not to every tier
+
+Verified 2026-09-01 (`git show <branch>:Database.php` in `_underscore`): the primitives added by
+this work (commit **`6355d0f0`** — `ERRNO_DUPLICATE_ENTRY = 1062`, `$lastErrorNumber`,
+`$retriableUniqueRace`, `wasRetriableUniqueRace()`) are on **`_production` and `_sandbox-client`
+only**. They are **absent from `_beta` and `_sandbox-dev`**.
+
+Because api2 clones `_underscore` from a **per-environment branch**, any app-side code that names
+`\_Database::ERRNO_DUPLICATE_ENTRY` **fatals with `Undefined constant` on beta and dev-sandbox** —
+and if the reference sits in a `catch` block, the fatal replaces the real error with a confusing one
+(seen in `Logs.Event` 7405 / 7404 on 2026-09-01). App-side callers should define their own `1062`
+constant and reach `$lastErrorNumber` through `property_exists()` until the framework side is on
+every branch. See
+[ENVIRONMENT decides the `_underscore` branch](./environment-variable-drives-underscore-branch.md)
+and [V2 request logging](./request-logging.md).
+
 ## Gotchas / known issues
 
 - Detection is built on the **MySQL errno** (1213/1205), not on matching the response text —
@@ -146,6 +164,13 @@ superglobal. Default is to leave a route off the list.
   not a substitute for removing the deadlock at its source.
 
 ## Change history
+- 2026-09-01 — Recorded the **deployment reach** of this work's `_underscore` primitives: commit
+  `6355d0f0` (`ERRNO_DUPLICATE_ENTRY`, `$lastErrorNumber`, `$retriableUniqueRace`,
+  `wasRetriableUniqueRace()`) is on **`_production` and `_sandbox-client` only** — **absent from
+  `_beta` and `_sandbox-dev`** — so api2 code naming `\_Database::ERRNO_DUPLICATE_ENTRY` fatals with
+  `Undefined constant` on those tiers (`Logs.Event` 7405 / 7404). App-side callers must define a local
+  1062 constant and read `$lastErrorNumber` via `property_exists()` until the branches catch up. No
+  code change to this feature. (bala)
 - 2026-08-28 — **Generalized Prong A to a second retriable class: the unique-key (1062)
   get-or-create race**, fixing the Compass ASN data-loss bug (`Logs.Issue #239`, EV-10) where a
   concurrent same-`ItemFulfillments.number` INSERT lost the race, `internalApiRequest` threw, and

package/knowledge/clients/nychh/features/netsuite-inventory-adjustment-fulfillment-link.md

@@ -6,7 +6,7 @@ project: Library
 client: nychh
 type: client-feature
 status: active
-updated: 2026-08-30
+updated: 2026-09-01
 owners: [jcardinal]
 files:
   - library/app/api/toga2.php
@@ -134,11 +134,22 @@ Both are framework-level NetSuite facts — full detail on
   **`mainline='F'` is the WRONG filter** — NetSuite sometimes marks the first real fulfilled line
   `mainline='T'`.
 
-## Two shared-engine fixes in `syncInventoryAdjustmentFromNetsuite` (surfaced here, affect any client)
+## Three shared-engine fixes in `syncInventoryAdjustmentFromNetsuite` (surfaced here, affect any client)
 
-Both are in the shared library method — see also the
+All in the shared library method — see also the
 [per-client sync](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md):
 
+- **(c) Serial-CASE mismatch missed the existing unit → 1062 freeze (fixed 2026-09-01).** The `/units`
+  reconciliation lookup was keyed by the **returned** unit serial (`$unit->serialNumber`, stored `'n/a'`)
+  but probed with the NetSuite serial **uppercased** via `strtoupper` (`'N/A'`). PHP array keys are
+  case-sensitive but `Units.itemId_serialNumber` is a **case-insensitive** unique key, so the existing
+  unit (id 546, itemId 560, serial `'n/a'`) was missed and re-INSERTed → MySQL **1062**
+  ("Duplicate entry '560-N/A'") → `EV-10` → section aborted (no per-record try/catch). This froze NYCHH
+  `INVENTORY_ADJUSTMENTS` at `1-RUNNING`, watermark stuck 2022-12-28 (integration was recently
+  restarted). **Fix:** key the lookup by `strtoupper($unit->serialNumber)`. The `Items.uuid=$uuidItem`
+  scoping was **kept deliberately** — copying the fulfillment "serial-only" lookup would be wrong for the
+  shared `'N/A'` placeholder serial (would reuse another item's placeholder unit). Section self-heals on
+  deploy. `library` only, working-tree, not yet committed/deployed.
 - **(a) Prune-order FK violation.** The stale-item prune deleted an `InventoryAdjustmentItem` while
   its child `InventoryAdjustmentItemUnits` still referenced it (FK **RESTRICT**, no cascade) → MySQL
   **1451** → `EV-11`. **Fix:** delete the child units (`/inventory-adjustment-item-units/{uuid}`)
@@ -197,9 +208,29 @@ this feature on the scheduled cron.
 - **Empty lookups drop or duplicate items.** The item loop filters to known warehouses and creates
   items on lookup-miss, so any manual/diagnostic invocation must seed the warehouse/item/manufacturer
   lookups (the harness does).
+- **A frozen NYCHH `INVENTORY_ADJUSTMENTS` section is NOT necessarily an item-matching / two-catalog
+  problem (verified 2026-09-01).** When the section stuck at `1-RUNNING`, item matching was suspected
+  (wrong of two intentional catalogs). Verified in prod it was fine: item **560**
+  (uuid `4c7b93d2-…`, partNumber **B11B242201**, HYBRID) is the Agilant-catalog item and the **only**
+  item with that part number — no duplicate second-catalog item, `$uuidItem` resolved correctly, and the
+  inventory-adjustment item-create already stamps catalog `Agilant`. The freeze was purely the serial-CASE
+  bug (fix (c) above). **Diagnosis chain (no NetSuite access):** `Client_Nychh.Parameters` (localize the
+  stuck section) → `Logs.Event` `clientId=3` (crash `toga2.php:6080` via
+  `common_sync_togasupply.php:1180` `syncInventoryAdjustmentFromNetsuite`, + `transactionId`) →
+  `Logs_Nychh.Api` on that `transactionId` (untruncated `EV-10`/1062 rejection + payload).
 
 ## Change history
 
+- 2026-09-01 — **Unfroze NYCHH `INVENTORY_ADJUSTMENTS` — serial-CASE mismatch in the `/units` lookup
+  (shared `library`, working-tree, not yet committed/deployed).** `syncInventoryAdjustmentFromNetsuite`
+  keyed the units lookup by the returned serial (`'n/a'`) but probed with the uppercased NetSuite serial
+  (`'N/A'`); PHP array keys are case-sensitive while `Units.itemId_serialNumber` is case-insensitive, so
+  the existing unit was missed, re-INSERTed, and 1062-collided → `EV-10` → section aborted at
+  `1-RUNNING` (watermark frozen 2022-12-28). Fixed by keying on `strtoupper($unit->serialNumber)`; kept
+  the `Items.uuid=$uuidItem` scoping (the shared `'N/A'` placeholder makes serial-only wrong here). Ruled
+  out item-matching / two-catalog as the cause (item 560 / B11B242201 is the only Agilant-catalog item,
+  `$uuidItem` correct). Diagnosed entirely from `Parameters` → `Logs.Event` (clientId 3) → `Logs_Nychh.Api`
+  by `transactionId`, no NetSuite access. (jcardinal)
 - 2026-08-30 — Verified that NYCHH adjustments with a NULL `itemFulfillmentId`/`itemFulfillmentItemId`
   are **correct, not a bug**: 0 of 27 NYCHH adjustments populate NetSuite `custbody_stock_adjustment`
   (~1 in 40 account-wide), so most carry no link. Confirmed the shim's scalar SuiteQL read of the field

package/knowledge/clients/nychh/profile.md

@@ -187,4 +187,9 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   path on any branch, and neither is in the working tree — so the transfer-order **custom-field
   write permission** and the **stage status identifier** are, like the ACL layers above, prod/local
   state with no file behind them. Rewrite them before anyone builds a fresh environment.
+- 🚨 **OPEN, not investigated (found 2026-09-01): recurring api2 `1054` errors for NYCHH.**
+  `Logs.Event` **issueId 64**, `clientId 3`: *"Database Error Occurred Error #: 1054 Unknown column
+  'vendor.uuid' in 'where clause'"* on a `PurchaseOrders` GET (`_Query->getFoundRows` via
+  `V2.php processRoutePairs`), several occurrences ~2026-09-01 12:29. Flagged for a future look; no
+  change made. Likely a TableView/query join referencing `vendor.uuid` that isn't in scope.
 - This profile is a starting point; expand as more NYCHH-specific behavior is captured.

package/package.json

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