toga-ai 1.0.928 → 1.0.929

package/knowledge/1.0/apps/library/features/netsuite-suiteql-api-reference.md

@@ -6,8 +6,8 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-09-30
-owners: ["dfranks", "jcardinal", "kyalamarthi", "ajean", "rgirish"]
+updated: 2026-10-01
+owners: ["dfranks", "jcardinal", "kyalamarthi", "ajean", "rgirish", "bala"]
 files:
   - library/app/api/netsuite/rest.php
   - library/ssl/netsuite_ec_key.pem
@@ -106,6 +106,7 @@ Type codes (`transaction.type`):
 
 Status codes (`transaction.status` letter):
 **Sales Orders:** `A` Pending Approval · `B` Pending Fulfillment · `C` Cancelled · `D` Partially Fulfilled · `E` Pending Billing/Partially Fulfilled · `F` Pending Billing · `G` Billed · `H` Closed. **"Open" sales orders = `B`, `D`, `E`, `F`.** Note `listSalesOrders()` returns **all** statuses for a window (no server-side status filter) — callers must filter.
+**Item Fulfillments (`ItemShip`):** `A` Picked · `B` Packed · `C` Shipped.
 **Invoices:** `A` Open · `B` Paid In Full. **Credit Memos:** `A` Open · `B` Fully Applied. **Cash Sales:** `A` Unapproved Payment · `C` Deposited. **Cash Refunds:** `Y` (the only status; empty string in SOAP).
 
 Header columns present (✓ confirmed in SuiteQL): `id`, `tranid`, `trandate`, `lastmodifieddate`, `type`, `status`, `entity`, `employee`, `leadsource`, `terms`, `memo`, `otherrefnum`, `foreigntotal`/`total` (both return the same value), `foreignamountunpaid` (AR balance — invoices only; NULL for SO/credit memo/cash sale), `duedate`, `shipmethod`, `opportunity`, `shippingaddress` (numeric id → join `transactionShippingAddress`), and custom fields (`CUSTBODY_END_CUSTOMER`, `CUSTBODY_STOCKING_ORDER`, …).
@@ -114,6 +115,25 @@ Header fields NOT in SuiteQL (✗ — require a per-id REST GET): `shippingCost`
 
 Tracking numbers in SuiteQL (verified 2026-09-28): `transaction.trackingnumberlist` (on the IF) / `linkedtrackingnumberlist` (on the SO) return **`trackingnumber` record ids**, not the numbers — resolve with `SELECT id, trackingnumber FROM trackingnumber WHERE id IN (...)`. `trackingnumbermap` returned nothing. The REST per-id GET below also has them.
 
+### Order → the transactions created FROM it: `nexttransactionlink`
+
+**`createdfrom` is a `transactionline` column — SuiteQL rejects it on `transaction`.** There is no
+header-level createdfrom to filter on. To find an order's fulfillments (or any child document), join
+`nexttransactionlink`:
+
+```sql
+SELECT ntl.previousdoc, ntl.nextdoc, t.tranid, t.type, t.status
+FROM nexttransactionlink ntl
+JOIN transaction t ON t.id = ntl.nextdoc
+WHERE ntl.previousdoc IN (<order internal ids>)
+```
+
+Pair it with the `ItemShip` status letters above to see how far each fulfillment got. This is how a
+**NYCHH transfer order** is traced: `Client_Nychh.TransferOrders.c_netsuiteInternalSalesOrderId`
+holds a NetSuite **sales order** internal id (a $0 SO *is* the transfer order — see
+[the outbound push](../../../2.0/apps/worker2/features/netsuite-transferorder-outbound-push.md)), so
+`previousdoc` is that id and the `ItemShip` rows that come back are its fulfillments.
+
 ### `transactionline` table
 
 Key columns (confirmed present): `transaction`, `linesequencenumber`, `uniquekey`, `id`, `item`, `itemtype`, `mainline`, `quantity`, `foreignamount`, `rate`, `costestimate`, `class`, `memo`, `quantitybilled`, `quantitycommitted`, `quantitypicked`, `quantityshiprecv`, `createdfrom`, `entity` (line-level customer), `location`, `subsidiary`.
@@ -271,4 +291,7 @@ SalesOrd per-id GET counts by `lastmodifieddate` window: ~16,600 (90d) / ~61,900
 - `../../worker/features/forecast2-netsuite-reconciliation.md` — the audit/trueup tooling that consumes this API.
 
 ## Change history
+- 2026-10-01 — Added `nexttransactionlink` as the order → child-document join (`createdfrom` is a
+  `transactionline` column and is rejected on `transaction`), and the `ItemShip` status letters
+  (`A` picked / `B` packed / `C` shipped). Found tracing NYCHH transfer orders. (bala)
 - 2026-09-30 — Gotcha: `inventorybalance.quantityavailable` ignores SO commitments; use `aggregateitemlocation`. (rgirish)

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

@@ -12,6 +12,7 @@
 | [Tools — Developers Folder (UUID & Password Generators)](features/developer-tools.md) | Tools "Developers" folder — the Generate UUID and Generate Password tools (reference example of the one-tool-per-`mvc/<route>/get.php` pattern); open for the ge |
 | [/emails Email Queue Review (Tools → 2.0 Logs_<Client>.Email)](features/email-queue-review.md) | Staff page to browse any 2.0 client's `Logs_<Client>.Email` queue and release/reject `HELD` review-hold emails. |
 | [/errors Curation Console (Tools → shared Core Logs DB)](features/errors-curation-console.md) | Internal-only 1.0 Tools triage/curation screen (`/errors`) for the 2.0 Issue/Event error pipeline, reading the shared Core Logs DB via `db_toga2logs`; curates, |
+| [Force Logout (tools /developers/force-logout → worker2 sets META_LAST_REFRESH_DATETIME)](features/force-logout.md) | Tools page that signs every 2.0 front-end user out after a big deploy by changing Core parameter `META_LAST_REFRESH_DATETIME` through a worker2 job; open to tri |
 | [GitHub Audit (monthly code-churn report)](features/github-audit.md) | Internal monthly code-churn report at `/developers/github-audit` (lines added/removed across every `agilantsolutions` repo for one month); open for the two-phas |
 | [Legacy Email Notifier (tools /email-migration/notify)](features/legacy-email-notifier.md) | SSO-gated admin tool at `/email-migration/notify` that emails employees a digest of mail still hitting their legacy domains (asks senders to switch to `@togatec |
 | [Tools — Multi-Client SQL (per-client-DB SQL fan-out)](features/multi-client-sql.md) | Tools `/developers/multi-client-sql` — fans one SQL change-set across a live list of 2.0 client/log/archive/module DBs into a copy/download script (never execut |

package/knowledge/1.0/apps/tools/features/force-logout.md

@@ -0,0 +1,46 @@
+---
+title: Force Logout (tools /developers/force-logout → worker2 sets META_LAST_REFRESH_DATETIME)
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-10-01
+owners: [bala]
+files:
+  - tools/_/app/developers/forcelogout.php
+  - tools/mvc/developers/force-logout/get.php
+  - tools/mvc/developers/force-logout/post.php
+  - tools/_/app/nav.php
+  - worker2/Worker/Platform/ForceLogout.php
+related:
+  - ./worker2-job-bridge.md
+  - ./developer-tools.md
+  - ../../../2.0/apps/toga2-commerce/features/force-logout-on-deployment.md
+  - ../../../2.0/apps/toga25-supply/features/force-logout-on-deployment.md
+---
+
+Tools page that signs every 2.0 front-end user out after a big deploy by changing Core parameter `META_LAST_REFRESH_DATETIME` through a worker2 job; open to trigger a force logout, or before touching `Core.Parameters` from code.
+
+## Summary
+
+Page `/developers/force-logout` (nav: Developers → Force Logout, persona **Development Team** only). Dev picks a date/time, presses Update. Replaces the old hand-written INSERT/UPDATE on `Core.Parameters` in prod. toga2-commerce and toga25-supply poll that key and log the user out on **any** change; the value itself does not matter (see the two FE docs in `related`).
+
+## How it works
+
+1. `post.php` actions: `load` (current value), `queue-update`, `job-status`.
+2. `App_Developers_ForceLogout::queueLogoutTimeUpdate()` validates strict `Y-m-d H:i:s` and **refuses a value equal to the stored one** (no change = no logout). Logs via `error_log` with the user uuid (audit).
+3. Queues `Platform/ForceLogout/SetLogoutTime` with `App_Worker::enqueue` (see [worker2-job-bridge](./worker2-job-bridge.md)).
+4. Page polls `job-status` every 2s: reads `WorkerJobs.isSuccess/dtStarted/output` scoped to this action only; shows only the first line of a failure, file paths stripped.
+5. worker2 `_Worker_Platform_ForceLogout::SetLogoutTime(value, requestedByUserUuid = '')` loads `_Model_Core_Parameter` by the hardcoded key, sets `value`, `save()`. Turns the query cache off first, then calls `_Database::transactionCommit(database: _underscore::DB_CORE)` explicitly.
+
+## Gotchas
+
+- **⚠ Never take the parameter key from input.** `Core.Parameters` also holds api2 secrets (`API_SECRET_ACCESS_TOKEN` etc). Key is a constant in both tools and worker2.
+- **`createFromFormat` alone accepts `2026-02-31`** (rolls over). Validate with a round trip: `format()` of the parsed date must equal the input.
+- **Works on prod tools only today.** Only `config.production.ini` has both `[worker]` (queue_url/queue_region) and `[database_toga2core]`. alpha has Core but no `[worker]`; no beta tools config has a worker queue.
+- **Deploy worker2 before tools**, or the first job fails with an unknown class.
+
+## Change history
+- 2026-10-01 — Built the page + worker2 action, replacing hand-run SQL on Core.Parameters. TRUE-82414. (bala)

package/knowledge/1.0/apps/tools/features/worker2-job-bridge.md

@@ -6,11 +6,12 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-09-23
-owners: [mhammontree]
+updated: 2026-10-01
+owners: [mhammontree, bala]
 files:
   - tools/_/app/worker.php
 related:
+  - ./force-logout.md
   - ../../../clients/compass-usa/features/people-file-import-admin-page.md
   - ./mvc-data-access-patterns.md
   - ../../../2.0/apps/worker2/architecture.md
@@ -63,6 +64,16 @@ empty result — because the wrapper format is worker2's, not a contract.
   `maxExecutionTime`. Never make a page wait for long work — poll, don't block.
 - **Deploy worker2 first.** A Tools page that calls a new action is broken until the action
   exists.
+- **Most tools configs cannot enqueue.** Only `config.production.ini` has a `[worker]` section
+  (queue_url/queue_region); alpha and beta tools have none.
+
+## Local testing (tools → worker2)
+
+1. Tools picks `config.<ENVIRONMENT>.ini` from the `ENVIRONMENT` env var; `config.dev-local.ini` is git-ignored and needs `[worker]` + the DB sections.
+2. Tools `composer install` fails on local PHP 8.1 (`symfony/filesystem` needs 8.2). Workaround: a git-ignored `tools/vendor/autoload.php` that requires worker2's vendor autoload.
+3. The AWS SDK ignores the host in `QueueUrl`. Set `AWS_ENDPOINT_URL_SQS` to a local fake SQS that POSTs the message body to `http://worker2/` (Laragon vhost).
+4. Dev-bypass login must use a `Client_True` email (e.g. `@togatech.com`, not `@goagilant.com`).
 
 ## Change history
+- 2026-10-01 — Added the local tools→worker2 test setup and the prod-only `[worker]` config fact (TRUE-82414). (bala)
 - 2026-09-23 — Created from TRUE-82250: documented the three `enqueue()` outcomes, the log-line-wrapped `output`, and the CTO decision that tools never speaks SFTP (phpseclib 1.x sha1-only KEX + credential duplication). (mhammontree)

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

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-09-30
+updated: 2026-10-01
 owners: ["dfranks", "bala", "jcardinal", "mhammontree", "snaredla", "rgirish"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -106,6 +106,10 @@ The value is `<seconds>-<STATE>`. Three readings, and only the first is a real f
 
 - **`1-RUNNING`** (window collapsed ÷3 to 1s) = throwing on **every** run = real freeze. Go read the
   error (`Logs.Event` by clientId → file:line → `Logs_<Client>.Api` on the transactionId).
+  **⚠ Nothing alerts on the way down.** `common_sync_togasupply.php:675-681` shrinks the window
+  ÷3 and the paired *"Interval is already at minimum but previous execution still failed to
+  finish"* throw is **commented out** (“so the script can continue”), so a phase degrades
+  864000 → … → **1 second** silently and never climbs back. Only the `Parameters` value shows it.
 - **A large-window `*-RUNNING`** (e.g. `864000-RUNNING`, `288000-RUNNING`) = **usually** healthy
   mid-run or a deliberate pause/backfill. **⚠ CORRECTED 2026-09-18 — this is NOT sufficient on its
   own, and the old "NOT stuck, do not fix it" wording caused a real miss.** NYCHH showed
@@ -577,6 +581,23 @@ purchase orders, invoices and item receipts were disabled again on 2026-09-03**
 is exactly why every NYCHH cursor stops at **2026-09-03**. Before concluding "the sync is broken",
 check the launcher's toggles at the relevant commit.
 
+### ⚠ NYCHH syncs ONCE A DAY — and its live state is in the CLIENT db, not Core
+
+Two traps that cost a diagnosis, both NYCHH-specific:
+
+- **The `*/5` schedule is not the real cadence.** `cron.worker.sync.json` registers
+  `sync_togasupply_hh.php` every 5 minutes like everyone else, but the wrapper calls
+  **`App_Framework::cronInitialization(86400)`** (“THIS CRON JOB IS INTENDED TO BE RUN EVERY DAY”),
+  so 287 of every 288 invocations exit immediately. Anything NetSuite ships after the morning run
+  waits until the next day. Account for that before calling a late import “broken” — and when
+  rewinding a cursor, run the wrapper by hand rather than waiting (the 10-day ceiling above means a
+  deep rewind would otherwise take weeks).
+- **Read `Client_Nychh.Parameters`, never the `NETSUITE_HH_*` keys in `Core`.** Core still carries
+  legacy `NETSUITE_HH_*` rows whose last-sync dates sit in **May 2026**; they are **stale leftovers
+  that nothing writes**. The live cursors and execution modes are
+  `NETSUITE_LAST_SYNC_CURSOR_*` / `NETSUITE_EXECUTION_MODE_*` in the client DB (see *Data model*).
+  Reading the Core copies leads straight to a wrong diagnosis.
+
 ### Replaying one order means rewinding the cursor by hand
 
 The cursor is a **seek** position (`<lastmodifieddate>|<internalId>`, see above), so an order whose
@@ -2044,6 +2065,12 @@ library (or vice versa) crashes GroWrk and Adyen on their next sync run.
   [NetSuite Sync Alert Monitor](../../library/features/netsuite-sync-alert-monitor.md).
 
 ## Change history
+- 2026-10-01 — NYCHH diagnosis traps recorded: the wrapper is gated to **once a day** by
+  `cronInitialization(86400)` despite its `*/5` schedule entry, and the live cursors/modes live in
+  `Client_Nychh.Parameters` — the `NETSUITE_HH_*` keys in `Core` are stale (May 2026) leftovers.
+  Also noted that the “interval already at minimum” throw is **commented out**
+  (`common_sync_togasupply.php:675-681`), so a phase can decay to a 1-second window with no alert.
+  (bala)
 - 2026-09-30 — Closed-order rule v3: drop only when every line is closed and nothing was created from it ([doc](../../library/features/netsuite-closed-order-rule.md)). Sync never auto-creates warehouse Locations (`throwIfUnknownWarehouse`); unit location from the line, not `custitemnumber_location`. Added `process_netsuite_records.php` and the stuck-sync diagnosis path. (rgirish)
 - 2026-09-24 — TO↔PO links: two-direction reconcile (vendor POs no longer upstream; retireStale moves downstream SO links to 326/330); fixed SO downstream line-link deletes on PO re-sync; new `process_netsuite_order.php` + `NETSUITE_SYNC_LOOKUPS_ONLY`. (jcardinal)
 - 2026-09-22 — **The `Logs.Issue` 589 doom-loop's framework root cause is now fully explained and has

package/knowledge/2.0/apps/toga2-commerce/features/force-logout-on-deployment.md

@@ -8,6 +8,7 @@ type: feature
 status: active
 updated: 2026-10-01
 owners: [apeterson]
+owners: [apeterson, bala]
 files:
   - toga2-commerce/src/hooks/useDeploymentGuard.tsx
   - toga2-commerce/src/lib/deploymentVersion.ts
@@ -15,6 +16,7 @@ files:
   - toga2-commerce/src/components/AuthLayout/AuthLayout.tsx
   - toga2-commerce/src/lib/authStorage.ts
 related:
+  - ../../../../1.0/apps/tools/features/force-logout.md
   - ./sso-redirect-and-session-gating.md
   - ./catalog-cache-freshness.md
   - ../../toga25-supply/features/force-logout-on-deployment.md
@@ -32,6 +34,8 @@ Ported from toga25-supply (`force-logout-on-deployment`). Two commerce-only diff
 
 Reached commerce `_production` only in merge `26e2fae7` (2026-09-30, TRUE-81991); supply had it earlier. That gap is why one parameter bump logged supply users out and commerce users not at all.
 
+**Trigger:** change the value with tools `/developers/force-logout` ([force-logout](../../../../1.0/apps/tools/features/force-logout.md)), not hand SQL.
+
 ## How it works
 
 1. One query on `META_LAST_REFRESH_DATETIME`, `enabled` only while authenticated, `staleTime: 0`, `refetchOnWindowFocus: true`, `refetchInterval` **5 minutes**.
@@ -76,4 +80,5 @@ To also fire on an in-app navigation: a `useLocation()` effect calling `refetch(
 
 ## Change history
 - 2026-10-01 — Documented the exact refetch triggers (mount / tab-visibility / 5-min poll; **not** route change), the background-pause behavior, the first-bump no-op, the ignored `key=` param, and the commerce-vs-supply query config difference. Route-change refetch deferred. (apeterson)
+- 2026-10-01 — Trigger is now the tools Force Logout page (TRUE-82414). (bala)
 - 2026-09-25 — Built for commerce: moved out of `AuthContext` into `<DeploymentGuard />` so a toaster can be shown; added 5-min poll + focus refetch; baseline key added to `AUTH_STORAGE_KEYS`. TRUE-81991. (apeterson)

package/knowledge/2.0/apps/toga25-supply/features/force-logout-on-deployment.md

@@ -7,12 +7,13 @@ client: shared
 type: feature
 status: active
 updated: 2026-10-01
-owners: [apeterson]
+owners: [apeterson, bala]
 files:
   - toga25-supply/src/hooks/useDeploymentGuard.tsx
   - toga25-supply/src/App.tsx
 related:
   - ../../toga2-commerce/features/force-logout-on-deployment.md
+  - ../../../../1.0/apps/tools/features/force-logout.md
 ---
 
 Force-signs-out every user when a deploy bumps a Core parameter, so session + caches reset to the new build; open when debugging surprise logouts or `useDeploymentGuard`.
@@ -21,6 +22,8 @@ Force-signs-out every user when a deploy bumps a Core parameter, so session + ca
 
 On large deploys the backend bumps Core parameter `META_LAST_REFRESH_DATETIME`. The FE watches it and, when it changes mid-session, force-signs-out every logged-in user so session, `localStorage`, and React Query cache (including the persisted `supply-chain-query-cache`) reset cleanly. Implemented as a headless `<DeploymentGuard />` driven by `useDeploymentGuard`, mounted inside the `AuthProvider` / `ToasterProvider` tree in `App.tsx` — **above** `<AppRouter />`, so the hook cannot use `useLocation()`.
 
+**Trigger:** change the value with tools `/developers/force-logout` ([force-logout](../../../../1.0/apps/tools/features/force-logout.md)), not hand SQL.
+
 ## How it works
 
 1. **Poll the Core parameter.** TanStack `useQuery` reads `META_LAST_REFRESH_DATETIME` via `apiGet("/core-parameters", { fields: ["value"], key: "META_LAST_REFRESH_DATETIME" })`, reading `response.data.coreParameters` (tolerant of an array or a single object). Query: `enabled` only while authenticated, `staleTime: 0`, `refetchOnWindowFocus: true`, `refetchInterval` 5 minutes.
@@ -32,5 +35,6 @@ On large deploys the backend bumps Core parameter `META_LAST_REFRESH_DATETIME`.
 **When it actually fires, the first-bump no-op, and the ignored `key=` param are identical here** — documented once in [commerce's force-logout doc](../../toga2-commerce/features/force-logout-on-deployment.md) (sections *What actually triggers a refetch* and *Gotchas*). Supply-only difference: `App.tsx` leaves `refetchOnWindowFocus` at React Query's default `true` app-wide, so every on-screen query refetches on tab visibility — not just this one. Sign-out timing is the same in both apps.
 
 ## Change history
+- 2026-10-01 — Trigger is now the tools Force Logout page (TRUE-82414). (bala)
 - 2026-10-01 — Recorded that the guard sits above the router (blocks `useLocation()`); moved the shared trigger/gotcha detail to the commerce doc rather than duplicating it. (apeterson)
 - 2026-09-16 — Initial implementation. (apeterson)

package/knowledge/INDEX.md

@@ -15,7 +15,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **test** (Test) — 16 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 3 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
 - **store** (Store) — 3 doc(s) → [1.0/apps/store/INDEX.md](1.0/apps/store/INDEX.md)
-- **tools** (Tools) — 23 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
+- **tools** (Tools) — 24 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 
 ## 2.0 framework
 
@@ -62,7 +62,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **ManageLife** (`managelife`) → [clients/managelife/INDEX.md](clients/managelife/INDEX.md)
 - **Northwell Health** (`northwell`) → [clients/northwell/INDEX.md](clients/northwell/INDEX.md)
 - **New York City Department of Education** (`nycdoe`) → [clients/nycdoe/INDEX.md](clients/nycdoe/INDEX.md)
-- **NYC Health & Hospitals** (`nychh`) → [clients/nychh/INDEX.md](clients/nychh/INDEX.md)
+- **NYC Health + Hospitals** (`nychh`) → [clients/nychh/INDEX.md](clients/nychh/INDEX.md)
 - **Office Depot** (`office-depot`) → [clients/office-depot/INDEX.md](clients/office-depot/INDEX.md)
 - **PC Matic B2B Client Profile** (`pcmaticb2b`) → [clients/pcmaticb2b/INDEX.md](clients/pcmaticb2b/INDEX.md)
 - **Prudential Financial** (`prudential`) → [clients/prudential/INDEX.md](clients/prudential/INDEX.md)

package/knowledge/clients/nychh/INDEX.md

@@ -1,4 +1,4 @@
-# Client: NYC Health & Hospitals `nychh`
+# Client: NYC Health + Hospitals `nychh`
 
 | Doc | Framework | Summary |
 |-----|-----------|---------|
@@ -10,4 +10,4 @@
 | [NYCHH transfer-order 2.0 model — inventory quantities + V2 field enablement](features/transfer-order-inventory-quantities.md) | 2.0 | NYCHH 2.0 transfer-order model — two-branch inventory quantities + the model/ACL work that lets a TransferOrder POST; open when NYCHH `_qty*` reads 0 or a Trans |
 | [NYCHH TransferOrder → NetSuite push (location roles, interceptor row 312, metadata state)](features/transfer-order-netsuite-push.md) | 2.0 | NYCHH is the **first and only** client on the outbound transfer-order push. |
 | [NYCHH transfer-order notification emails (Submitted / Packed / Shipped)](features/transfer-order-notification-emails.md) | 2.0 | NYC Health + Hospitals (H+H) gets three notification emails for a transfer order raised in **TOGa Supply**: **Submitted**, **Packed** and **Shipped**. |
-| [NYC Health & Hospitals](profile.md) | 2.0 | NYC Health & Hospitals (NYCHH) client profile — open for supply-chain / TransferOrder / NetSuite-sync work on prod schema `Client_Nychh`. |
+| [NYC Health + Hospitals](profile.md) | 2.0 | NYC Health & Hospitals (NYCHH) client profile — open for supply-chain / TransferOrder / NetSuite-sync work on prod schema `Client_Nychh`. |

package/knowledge/clients/nychh/features/transfer-order-notification-emails.md

@@ -6,13 +6,14 @@ project: Worker
 client: nychh
 type: client-feature
 status: active
-updated: 2026-09-24
+updated: 2026-10-01
 owners: ["bala", "rgirish", "jcardinal"]
 files:
   - worker2/Worker/Client/Nychh/TransferOrderEmails.php
   - _underscore/Model/Nychh/TransferOrder.php
   - _underscore/Model/Nychh/ItemFulfillment.php
   - dbchanges2/Client_Nychh/2026-09-15a - TransferOrderEmails.sql
+  - dbchanges2/Client_Nychh/2026-09-30a - TransferOrderPackedAssetTagException.sql
   - dbchanges2/Client_Nychh/2026-09-15b - TransferOrderEmailGoLiveRecipient.sql
   - dbchanges2/Core/2026-09-16a - NychhTransferOrderEmailsCron.sql
 related:
@@ -47,6 +48,8 @@ Three rules carry most of the risk:
 2. **Only orders raised in TOGa Supply may be announced.** `TransferOrders.createdByUserId` is the
    discriminator; without it H+H would be mailed about every order the NetSuite sync ever imported.
 3. **A failed send throws — it is never swallowed**, so nothing is ever marked sent that did not go.
+4. **Packed (and shipped) are HELD while a line is short of asset tags** — ops is warned instead, and
+   the customer email sends itself once the tags land. See below.
 
 Recipient is `DevTeam@togatech.com` while testing. `2026-09-15b` swaps it to
 `EndUserDeviceLifecycle@nychhc.org` — run that file only after sign-off.
@@ -57,6 +60,8 @@ Recipient is `DevTeam@togatech.com` while testing. `2026-09-15b` swaps it to
   - `SendSubmitted(string $transferOrderUuid)` — queued from the TransferOrder `postPut`.
   - `SendFulfillment(string $itemFulfillmentUuid)` — queued from the ItemFulfillment hooks.
   - `SendPending(bool $dryRun = true)` — the `*/5` backstop cron.
+  - `resolveStagesStillToAnnounce()` — which stages are still owed (see the late-shipped case).
+  - `readLinesMissingAssetTags()` / `sendPackedExceptionEmail()` — the asset-tag hold.
   - `initialize()` registers the client DB before any query runs.
   - Builders: `buildItemRowsHtml()`, `buildTrackingSectionHtml()`, `buildAssetTagTableHtml()`,
     `escapeForEmailHtml()`; budget constant `MAXIMUM_EMAIL_BODY_BYTES`.
@@ -70,6 +75,8 @@ Recipient is `DevTeam@togatech.com` while testing. `2026-09-15b` swaps it to
   - submitted `0f4a6c21-9d3e-4b87-a15c-6e2b8f70d914`
   - packed `7b1d9e54-3c62-48af-b0d7-25f4a8c31e6b`
   - shipped `c58f3a07-6b94-4d21-8e3f-914ad7b06c52`
+  - packed **exception** (internal warning, seeded by `2026-09-30a`)
+    `9d3b1e6a-47c2-4f85-b019-2ae85c7d4630`
 - **`nychh_email_templates/*.html`** — ⚠ the HTML source of the three templates. **These files are
   in no git repo** — they live only in the working folder. The dbchanges2 seed SQL is generated
   *from* them, so the `EmailTemplates` rows in `2026-09-15a` are the only durable copy.
@@ -114,6 +121,14 @@ they must stay in step: the Submitted guard, the order read, and both `SendPendi
 2. **Packed / Shipped** — the ItemFulfillment `postPost` / `postPut` queue `SendFulfillment` with
    the fulfillment uuid. The stage reached is recorded on `c_transferOrderEmailStageSent`, with
    `c_dtTransferOrderEmailSent` as the timestamp, so a fulfillment cannot re-announce a stage.
+   `resolveStagesStillToAnnounce()` decides what is owed: normally the one stage reached, but when a
+   fulfillment **arrives already shipped** and packed was never announced it returns
+   **`[packed, shipped]`** and both send in that order in one run. Before this the packed stage was
+   skipped outright — and **the asset-tag check lives on packed**, so a late shipped fulfillment
+   bypassed it completely. Real case: transfer order **291773** got Submitted and Shipped, never
+   Packed. The NYCHH NetSuite sync is a **daily** cron, so a fulfillment landing fully shipped is
+   normal, not an edge case — see
+   [the per-client sync](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
 3. The **backstop cron** sweeps anything the hooks missed (below).
 4. All three paths share the same markers, so nothing sends twice.
 5. The worker renders the stored `EmailTemplates` body, fills `{orderItems}` and
@@ -137,6 +152,42 @@ PUT follows.** Fulfillment **2704** in production: header row at 20:33:09, lines
 - It also picks up any send that threw (the marker was never written).
 - Caps at **25 of each kind per run** (`MAXIMUM_EMAILS_PER_RUN`).
 
+## ⚠ Missing asset tags HOLD the packed email (and warn ops instead)
+
+Added 2026-09-30 (TRUE-82111). `SendFulfillment` runs `readLinesMissingAssetTags()` whenever
+**packed** is one of the stages still owed. A fulfillment line counts as **short** when either:
+
+- it has **fewer linked units than its quantity** (`unitsLinked < ItemFulfillmentItems.quantity`), or
+- a linked unit has a **blank `Units.assetTag`**.
+
+When any line is short, `SendFulfillment` **returns before writing
+`c_transferOrderEmailStageSent`** — so packed stays pending and the backstop cron re-sends it by
+itself the moment the tags arrive. **The hold covers shipped too**, because the early return happens
+before the stage loop.
+
+Instead, an **internal** warning goes out on template `9d3b1e6a-47c2-4f85-b019-2ae85c7d4630`
+(`2026-09-30a`): **to `operations@togatech.com`, CC `HealthcareteamNYCHHC@togatech.com`** —
+**never the client**. It lists one row per short line. Subject carries both numbers so it is
+searchable:
+
+```
+Action needed: asset tags missing on transfer order {transferOrderNumber}, fulfillment {itemFulfillmentNumber}
+```
+
+- **It warns once per fulfillment, not every five minutes.** New custom field
+  **`c_dtTransferOrderPackedExceptionSent`** on `ItemFulfillments` (record **28**) is the marker;
+  `sendPackedExceptionEmail()` returns early when it is already set, and stamps it only after a
+  successful send.
+- **⚠ Warned rows must still be SELECTED by the cron, just sorted last.**
+  `sendPendingFulfillmentEmails()` takes `LIMIT 25` per run, and a held fulfillment keeps
+  `c_transferOrderEmailStageSent` NULL forever, so 25 stuck rows would sit at the front of every run
+  and starve everyone else. The order is now
+  `ORDER BY (c_dtTransferOrderPackedExceptionSent IS NOT NULL) ASC, id ASC`. **Do not filter them
+  out** — that strands them permanently; they must still be picked up the run after the tags land.
+
+See [the NYCHH asset-tag backfill](../../../2.0/apps/worker2/features/nychh-asset-tag-backfill.md)
+for where the tags come from.
+
 ## Schema, registration and deploy order
 
 `dbchanges2/Client_Nychh/2026-09-15a - TransferOrderEmails.sql` carries the whole feature:
@@ -145,6 +196,8 @@ PUT follows.** Fulfillment **2704** in production: header row at 20:33:09, lines
 |---|---|
 | `c_dtTransferOrderSubmittedEmailSent` | `TransferOrders` (record **312**) |
 | `c_transferOrderEmailStageSent`, `c_dtTransferOrderEmailSent` | `ItemFulfillments` (record **28**) |
+| `c_dtTransferOrderPackedExceptionSent` (`2026-09-30a`) | `ItemFulfillments` (record **28**) |
+| The packed-exception `EmailTemplates` row + its TO/CC rows (`2026-09-30a`) | `Client_Nychh` |
 | The three `EmailTemplates` rows + recipient rows | `Client_Nychh` |
 | `CustomRecordFields` rows + `AclCustomFieldPermissions` grants (Base and API) | `Client_Nychh` |
 | The record-312 **PUT** interceptor row | `ApiPayloadInterceptors` |
@@ -255,9 +308,22 @@ Cost of the split, stated so nobody is surprised later:
   `Logs_Nychh.Email` without an inbox — that is how these were verified. See
   [the email send pipeline](../../../2.0/apps/_underscore/features/email-send-pipeline.md).
 - **The `nychh_email_templates/*.html` sources are not version-controlled** (see *Key files*).
+- **⚠ An email that leaves the dev team never describes internal process.** The packed-exception
+  body first explained NetSuite, TOGa Supply, the sync and the five-minute retry; all of it was
+  removed on instruction. An email says **what happened, what to do, and that it is handled** —
+  nothing about which system, which cron, or how often we retry. Process detail belongs in code
+  comments and the dbchanges2 header. Applies to every template here, not just the exception one.
+- **⚠ The ops / healthcare-team addresses have never actually been exercised.** On dev sandbox the
+  debug redirect rewrites every recipient, so the `operations@togatech.com` TO and the
+  `HealthcareteamNYCHHC@togatech.com` CC on the exception template are unproven until prod. Check the
+  first live exception email lands on both.
 
 ## Testing
 
+**106 tests** as of 2026-09-30. Each fix is proven by **reverting it** and confirming the matching
+tests fail. The five scenarios were then run end to end on **dev sandbox** against fulfillment
+**898** / transfer order **286536**.
+
 A local end-to-end harness (scratchpad, **not committed**) runs the **real** worker class against a
 throwaway local schema built with `CREATE TABLE LIKE` from `Client_Nychh`, stubbing **only**
 `_Query` / `_Database` / `_Model_Client_EmailTemplate`, and rendering the **real** template bodies
@@ -266,6 +332,19 @@ loaded out of the dbchanges2 file so an unresolved `{placeholder}` fails a test.
 unescaped values and both detail-box defects were all found there, not in production.
 
 ## Change history
+- 2026-10-01 — **Packed/shipped are now HELD when a fulfillment line is short of asset tags**
+  (TRUE-82111). A line is short when it has fewer linked units than its quantity **or** a linked unit
+  has a blank `assetTag`; `SendFulfillment` then returns without writing
+  `c_transferOrderEmailStageSent`, so the customer email sends itself once the tags land, and an
+  internal warning goes to `operations@togatech.com` (CC `HealthcareteamNYCHHC@togatech.com`) once
+  per fulfillment via new marker `c_dtTransferOrderPackedExceptionSent` and template
+  `9d3b1e6a-…` (`2026-09-30a`). Two fixes came with it: `resolveStagesStillToAnnounce()` now sends
+  **packed then shipped in one run** when a fulfillment arrives already shipped (transfer order
+  **291773** had Submitted + Shipped and no Packed — which also meant it skipped the asset-tag
+  check), and `sendPendingFulfillmentEmails()` sorts warned rows **last**
+  (`ORDER BY (c_dtTransferOrderPackedExceptionSent IS NOT NULL) ASC, id ASC`) so 25 held rows cannot
+  fill the `LIMIT 25` and starve every other fulfillment. Also recorded the rule that outbound emails
+  never describe internal process. (bala)
 - 2026-09-24 — `TransferOrderEmails` reads PO numbers from upstream bridge 325 (column `purchaseOrderId` dropped). (jcardinal)
 - 2026-09-23 — Submitted template put on review hold; missing REVIEW row → job failure note. (jcardinal)
 

package/knowledge/clients/nychh/profile.md

@@ -1,5 +1,5 @@
 ---
-title: "NYC Health & Hospitals"
+title: "NYC Health + Hospitals"
 framework: "2.0"
 apps:
   - _underscore
@@ -18,7 +18,7 @@ project: _Underscore
 client: nychh
 type: profile
 status: active
-updated: 2026-09-30
+updated: 2026-10-01
 owners: ["jcardinal", "apeterson", "bala", "akhokhani"]
 files:
   - dbchanges2/Client_Nychh/2026-09-02a - TransferOrderNetsuitePushInterceptor.sql

package/package.json

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