toga-ai 1.0.528 → 1.0.530

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

@@ -6,8 +6,8 @@ project: Library
 client: shared
 type: feature
 status: active
-updated: 2026-08-04
-owners: [jcardinal, mhammontree]
+updated: 2026-08-05
+owners: [jcardinal, mhammontree, bala]
 files:
   - library/app/api/toga2.php
   - worker/crons/toga2/aig/sync_togasupply_aig.php
@@ -275,6 +275,14 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
 
 ## Gotchas / known issues
 
+- **A 2.0 GET silently TRUNCATES a nested child collection — never trust a single response for a
+  count.** When you read a parent with a nested `hasMany` collection in one GET, api2 can return the
+  collection **partial** (observed: a fulfillment's nested `itemFulfillmentItemUnits` came back **45
+  of 70**) with no error and no obvious signal — so any verification that counts off the nested array
+  is silently wrong. **Read the collection flat and fully paginated** (query the child resource
+  directly with the universal `meta->nextPage` loop) and take counts from **`meta.totalRecordCount`**,
+  not from a single nested response. Surfaced building the NYCHH fulfillment asset-tag verifier
+  (`worker/crons/toga2/netsuite/verify_fulfillment_asset_tag_sync_nychh.php`).
 - **🔐 Hardcoded credentials.** Every client's `CLIENT_UUID_*`, `API_UUID_*`, and `API_SECRET_*`
   (plus the "True Workers" master keys) are committed as plaintext class constants at the top of
   `toga2.php`. Treat them as **compromised-if-leaked**; do not reproduce the values in the KB,
@@ -353,6 +361,10 @@ enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
 
 ## Change history
 
+- 2026-08-05 — Recorded that a 2.0 GET **silently truncates a nested child collection** (observed
+  `itemFulfillmentItemUnits` 45 of 70) with no error — so verification/counts must read the child
+  resource **flat + fully paginated** and use `meta.totalRecordCount`, never a single nested
+  response. Surfaced building the NYCHH fulfillment asset-tag verifier. (bala)
 - 2026-08-04 (**uncommitted/undeployed** at time of writing) — `authenticate()` now records the
   ambient client uuid for error reporting (`App_Error_Capture::setCurrentClientUuid()`, store-only)
   because it is the one place every 1.0→2.0 cron passes through holding its `UUID_CLIENT` — this is

package/knowledge/1.0/apps/togaview/architecture.md

@@ -108,9 +108,15 @@ divergent shapes (read `emailAddress` with `email` fallback).
 
 **SAML** (rumcsi, towfoundation, newcenturyholdingsllc) is handled in `framework.php`
 (`meta`/`acs`/`sls`); newcenturyholdingsllc and towfoundation **auto-create `people` rows** for
-unknown SAML users. rumcsi additionally accepts a legacy `?hash=<base64 email>` auto-login — **an unauthenticated
-account-takeover path that appears to be the client's actual production login**; do not remove it
-before completing the `acs` handler (see [login flows](features/login-flows.md)).
+unknown SAML users. rumcsi additionally accepts a `?hash=<base64 email>` auto-login — **an unauthenticated
+account-takeover path that is also, per the routing evidence, RUMC's live production SSO login**:
+the block holds the only rumcsi route to `/enterprise_dashboard` (where a real production SSO
+login lands), and togaview has no `?saml=` handling, so the 2.0 SAML gateway is not involved.
+Only rumcsi's `acs` handler fails to populate the session (newcenturyholdingsllc `:819` and
+towfoundation `:1180` do), which is why only rumcsi has a magic link. **Deleting it breaks RUMC
+login into an IdP redirect loop** — sign the token or complete the `acs` handler instead, in
+coordination with the external link generator. A cold-login capture to confirm the inbound
+`?hash=` hop is still outstanding (see [login flows](features/login-flows.md)).
 
 ## Dashboards
 Five dashboards, one per audience/business model, each delegating to a client override or the

package/knowledge/1.0/apps/togaview/features/login-flows.md

@@ -72,26 +72,65 @@ lookup silently found nothing. Removed, and `email LIKE '…'` changed to `=` in
 
 ## Gotchas / known issues
 
-### OPEN SECURITY ITEM — rumcsi `?hash=` unauthenticated account takeover (deliberately left in place)
+### OPEN SECURITY ITEM — rumcsi `?hash=` is the LIVE production SSO login (do not delete it)
 `_/app/framework.php` authenticates a rumcsi user on nothing but
 `base64_decode(urldecode($_GET['hash']))` matching an active `people` row for the rumcsi
 clientid — **no password, signature, nonce, or expiry** — then populates ~18 session keys and
 redirects to `/enterprise_dashboard`. Anyone who can guess a RUMC user's email can log in as
 them.
 
-It was removed during TRUE-80671 and then **deliberately reverted**, because it may BE the
-production login mechanism: the rumcsi SAML `acs` handler does `App_MVC::routeTo('/')` on success
-and **never populates `$_SESSION`** (unchanged since commit 9e7d306, "phase one … make sure
-redirect works"); repo-wide only two places ever build a rumcsi session — this hash block and
-`mvc/login/post.php:462`, and the latter is unreachable because the SAML gate redirects to the
-IdP before a password POST can be processed; and RUMC login is confirmed **working in
-production**. Nothing in togaview/togadesk/library generates such a link, so links are presumably
-generated outside our codebase.
-
-- **Next step:** obtain the post-SSO redirect URL from Jonathan to confirm whether it carries
-  `hash=`.
-- **Proper fix:** complete the rumcsi `acs` handler (mirror newcenturyholdingsllc:
-  `$auth->getNameId()` → `people` lookup → session build) — **not** restoring the bypass.
+It was removed during TRUE-80671 and then **deliberately reverted**. Routing evidence gathered
+afterwards shows this is not a dormant legacy backdoor — it is **how RUMC actually logs in**:
+
+- Jonathan performed a real production SSO login and was returned to
+  `https://rumcsi.togaview.agilantsolutions.com/enterprise_dashboard`.
+- Inside the rumcsi block, **`framework.php:278` is the ONLY path to `/enterprise_dashboard`** —
+  and it sits **inside the hash block**, behind `if ($rumcsiUser)`. The SAML `acs` handler instead
+  does `App_MVC::routeTo('/')`. The only other RUMC route to that page is
+  `mvc/login/post.php:511`, which is the *password* login. **Landing on `/enterprise_dashboard`
+  after an SSO login is the hash block's signature.**
+- The absence of `?hash=` in the final URL is **expected, not exculpatory**: the block consumes
+  the parameter and issues a fresh redirect, so the query string is gone from the address bar.
+- **The modern alternative is ruled out.** The 2.0 SAML gateway (repo `saml`,
+  `Controller/Index.php:456-460`) hands off with `?saml=<base64 JSON whose client and user UUIDs
+  are encrypted via `_String::encryptWithKey`>` — the correct mechanism, which `tools` uses.
+  togaview has **zero** handling for `?saml=` (no `$_GET['saml']` anywhere). RUMC does not come
+  through that gateway, and there is no hidden session-population path.
+- **Had the deletion shipped, RUMC SSO would have broken outright:** authenticate at the IdP →
+  `acs` → `/` → no `contactId` → bounced back to the IdP. A redirect loop, not a login. The
+  revert was correct.
+
+**Still open — who generates the link.** Nothing in togaview/togadesk/library builds a `hash=`
+URL, so the generator is external (likely RUMC's IdP-initiated flow or their own portal).
+**Confirming test:** a **cold** SSO login in a private window with DevTools → Network →
+*Preserve log*, capturing the full redirect chain and checking whether the hop **into** togaview
+carries `?hash=`. Jonathan's test may not have exercised a cold login at all — with a live session
+cookie the `!array_key_exists('contactId', $_SESSION)` gate is skipped entirely and
+`/enterprise_dashboard` is simply where he already was.
+
+**Fix shape — a coordinated change, never a deletion.** Two options, both requiring coordination
+with whoever generates the link:
+- **(a) Keep the handoff but sign it.** Replace the unsigned base64 email with an HMAC-signed
+  token via `App_String::encrypt`/`decrypt` (`library/app/string.php`). Smallest change; kills
+  guessability.
+- **(b) Complete the rumcsi `acs` handler** so it builds the session itself, then retire the
+  handoff.
+
+⚠ **Do NOT delete the block first, under either option.**
+
+### Why rumcsi is the only one of the three SAML clients with a magic-link login
+The real lesson is the contrast between the three `acs` handlers in `_/app/framework.php`:
+
+| Client | `acs` handler | Sets `contactId` / session? |
+|---|---|---|
+| newcenturyholdingsllc | `:819` | **Yes** — completes the login |
+| towfoundation | `:1180` | **Yes** — completes the login |
+| rumcsi | `:399-417` | **No** — only `routeTo('/')` (since 9e7d306, "phase one … make sure redirect works") |
+
+rumcsi's handler was never finished, and the `?hash=` block is what filled the gap. When adding a
+SAML client, the `acs` handler **must** populate the session — an unfinished one invites exactly
+this kind of unsigned side door.
+
 - Note the surviving SAML branch is gated on `!inTestMode()`, so **test mode leaves rumcsi with
   no login path at all**.
 
@@ -106,6 +145,14 @@ generated outside our codebase.
 - The flows are order-dependent: a contact matching an earlier flow never reaches later ones.
 
 ## Change history
+- 2026-08-05 (later, TRUE-80671) — **Upgraded the rumcsi `?hash=` finding from "may be" to
+  evidenced:** `framework.php:278` inside the hash block is the only rumcsi route to
+  `/enterprise_dashboard`, where a real production SSO login landed; togaview has no `?saml=`
+  handling at all, so the 2.0 SAML gateway is ruled out; deleting the block would have produced an
+  IdP redirect loop, not a login. Recorded the three-way `acs` handler contrast (newcentury :819 /
+  towfoundation :1180 populate the session, rumcsi :399-417 never did), both fix shapes (sign the
+  token with `App_String::encrypt`, or finish `acs`), and the outstanding cold-login DevTools test.
+  (mhammontree)
 - 2026-08-05 (TRUE-80671, uncommitted) — Fixed the unguarded `$user_name[1]` session-name build
   that **locked mononym / shared-mailbox users out entirely** (4 sites); removed
   `sqlProtect(sqlEscape())` and switched email lookups to `=`; recorded the rumcsi `?hash=`

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-07-09
+updated: 2026-08-05
 owners: ["dfranks", "bala", "jcardinal"]
 files:
   - worker/crons/toga2/netsuite/common_sync_togasupply.php
@@ -91,6 +91,32 @@ places or the sync runs but imports nothing (or 403s). All five steps are requir
    The most commonly-missing one is `c_netsuiteInternalCustomerId` on the **Customers** record
    (`recordId 113`, `isIdentifier=1`).
 
+### Item-fulfillment section is a FULL reconcile (like `syncSalesOrderFromNetsuite`)
+
+`App_Api_Toga2::syncItemFulfillmentFromNetsuite` (`library/app/api/toga2.php`) is now a **full
+reconcile**, not an append: on every re-sync it makes TOGa **match NetSuite**. It updates item
+fulfillment items and units, sets serial / `assetTag` / `macAddress` (**never blanking** a value
+that is already populated), and maintains **all three tracking bridges** —
+`ItemFulfillments_TrackingNumbers` (record 317, header), `ItemFulfillmentItems_TrackingNumbers`
+(318, item), `ItemFulfillmentItemUnits_TrackingNumbers` (319, unit). It **prunes** units/items that
+NetSuite has dropped, **deleting their tracking-bridge links FIRST** because those bridge FKs are
+`RESTRICT` (no cascade) — delete the bridge rows before the parent unit/item or the delete errors.
+See the [tracking-number bridge doc](../../../2.0/apps/_underscore/features/tracking-number-bridges.md).
+
+- **Record 318 is fetched in its own isolated GET.** 318 is deliberately excluded from the main
+  fulfillment GET: requesting a field a role cannot read **403s the whole GET**, so 318 is
+  reconciled in a separate try/catch GET that can fail without taking the rest down.
+- **Re-sync trigger is the ItemShip `lastmodifieddate`.** A tag added later only to the
+  serial/inventory-number record does **not** bump the fulfillment, so late tags are **not** caught
+  here — they are handled by the separate per-client asset-tag backfill/cron (e.g. NYCHH's, see
+  [nychh-asset-tag-backfill](../../../2.0/apps/worker2/features/nychh-asset-tag-backfill.md)).
+- **Upstream-mirror interaction is a cheap no-op for non-Compass clients.** Any
+  `/item-fulfillments`, `/item-fulfillment-items`, `/item-fulfillment-item-units` POST/PUT fires
+  `_underscore`'s `_Model_Client_ItemFulfillment::ensureUpstreamItemFulfillment` (the Compass
+  multi-tier SO→PO→SO mirror), but it is a ~2-query no-op for NYCHH / Quad / Prudential (verified:
+  0 of their fulfillments resolve an upstream sales order). `/units` writes and all three
+  tracking-bridge models have **no** interceptor, and **DELETE fires none**.
+
 ### Custom field contract (hardcoded in `common_sync_togasupply.php`)
 
 The engine requests these `c_` fields by literal name per route — every synced client must have
@@ -211,6 +237,15 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
 
 ## Change history
 
+- 2026-08-05 — Documented that `syncItemFulfillmentFromNetsuite` is now a **full reconcile** like
+  `syncSalesOrderFromNetsuite`: updates IF items/units + serial/`assetTag`/`macAddress`
+  (never blanking), maintains **all three** tracking bridges (317/318/319), and **prunes**
+  dropped units/items **deleting their bridge links first** (bridge FKs are `RESTRICT`). Record
+  318 is reconciled in its own isolated try/catch GET (a forbidden field 403s the whole GET);
+  re-sync trigger is the ItemShip `lastmodifieddate` (serial-only tag edits are handled by the
+  separate asset-tag backfill). The upstream-mirror interceptor
+  (`ensureUpstreamItemFulfillment`) is a ~2-query no-op for NYCHH/Quad/Prudential (0 upstream SOs);
+  `/units` + the bridge models have no interceptor and DELETE fires none. (bala)
 - 2026-07-22 — Recorded the **dual-catalog duplicate OD PO-line bug** in
   `syncSalesOrderFromNetsuite` (uuid-only PO-line reconciliation → shadow-VendorItem duplicate
   lines) and its SKU-fallback fix. Compass cleanup + sequencing captured in the

package/knowledge/2.0/apps/_underscore/features/netsuite-rest-client.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-21
-owners: ["dfranks", "jcardinal"]
+updated: 2026-08-05
+owners: ["dfranks", "jcardinal", "bala"]
 files:
   - _underscore/Component/Api/Netsuite/Netsuite.php
 related:
@@ -131,6 +131,20 @@ would corrupt values like `O'Brien`. Use `str_replace("'", "''", $value)` to esc
 string literal. (worker2's `SalesOrder.php` carries this as a private `escapeSuiteQl()` helper;
 any new SuiteQL caller must do the same.)
 
+## SuiteQL custom columns are SELECT-only — you cannot filter (WHERE) on them
+
+You **can `SELECT`** a NetSuite custom column in SuiteQL, but you **cannot put it in a `WHERE`**.
+On the `inventorynumber` table, `SELECT custitemnumber_asset_tag, custitemnumber_mac_address` returns
+the values fine — but `WHERE custitemnumber_asset_tag IS NOT NULL` (or any predicate on a custom
+column) returns **0 rows with NO error**. It fails silently, so it looks like "no matching data"
+rather than a bad query. Confirmed live 2026-07-28.
+
+**Drive the query off a native column instead**, then filter in PHP: query
+`WHERE inventorynumber IN ('serial1','serial2',…)` (chunk over the serials/keys you already have —
+500 at a time works), `SELECT` the custom columns alongside, and drop blanks in PHP after the fetch.
+Surfaced building the NYCHH asset-tag backfill (see
+[nychh-asset-tag-backfill](../../worker2/features/nychh-asset-tag-backfill.md)).
+
 ## Logging
 
 `send()` calls `setLogging(false)`, so **NetSuite REST request/response bodies are NOT written to
@@ -155,6 +169,11 @@ doc.)
 
 ## Change history
 
+- 2026-08-05 — Recorded the **SuiteQL custom-column filter trap**: a NetSuite custom column
+  (e.g. `inventorynumber.custitemnumber_asset_tag`/`_mac_address`) can be `SELECT`ed but **not**
+  filtered on — `WHERE custitemnumber_asset_tag IS NOT NULL` returns 0 rows with no error. Drive
+  the query off a native column (`WHERE inventorynumber IN (...)`, chunked) and filter blanks in
+  PHP. Surfaced building the NYCHH asset-tag backfill. (bala)
 - 2026-07-21 — **Documented the auth mechanism, config-key locations, `send()` signature, and the
   `RECORD_*`/query/metadata constant catalog** (folded in from a retired project-local
   `worker2/netsuite/CLAUDE.md`). Auth = OAuth 2.0 certificate-signed JWT client assertion

package/knowledge/2.0/apps/_underscore/features/tracking-number-bridges.md

@@ -6,8 +6,8 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-14
-owners: ["jcardinal", "mhammontree", "dfranks", "apeterson"]
+updated: 2026-08-05
+owners: ["jcardinal", "mhammontree", "dfranks", "apeterson", "bala"]
 files:
   - api2/Component/Api/V2/V2.php
   - _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php
@@ -121,6 +121,13 @@ returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTracki
 
 - **Tracking is now an inherent child, not a scalar.** Any producer that sent a flat `trackingNumber`
   on a unit must nest it under the unit's `*TrackingNumbers` child array, or it is silently dropped.
+- **Pruning a unit/item means deleting its bridge rows FIRST — the bridge FKs are `RESTRICT`, not
+  cascade.** The IF bridge FKs (`ItemFulfillments/Items/ItemUnits_TrackingNumbers` → parent) are
+  `ON DELETE RESTRICT`, so deleting a parent unit/item that NetSuite dropped errors unless you delete
+  its 317/318/319 bridge links first. The 1.0 `App_Api_Toga2::syncItemFulfillmentFromNetsuite` full
+  reconcile does exactly this (delete bridges, then parent). Any code that prunes IF units/items must
+  do the same ordering. See the
+  [per-client sync doc](../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md).
 - **Migration FK pitfalls (all handled in the SQL):** deleting `RecordFields` hits `DefaultRecordFieldSettings`
   FKs (repoint first); deleting `AclRecordPermissions` hits the `AclLogicGroups`→`AclLogicGroupExpressions`
   chain (record-41 teardown wraps it in `SET FOREIGN_KEY_CHECKS=0`); deleting `TableViewFields` hits
@@ -173,6 +180,10 @@ returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTracki
 - **Porting the item-fulfillment TableView fix to another client is two independent decisions, not a copy-paste.** The **re-root** (Units 31 → ItemFulfillmentItems 29 + OUTER unit chain) is universally portable and fixes the "0 records" bug everywhere. The **tracking source is client-specific**: Compass writes one tracking number per item fulfillment at the **item level (318)**, so its views read 318. Other clients populate different bridge levels — verify with `SELECT COUNT(*)` per bridge before choosing. As of 2026-06-19, **record 318 is empty in `Client_Nychh` and `Client_Quad`**; their tracking lives at the **IF/shipment level (317)** (covers IFIs: NYCHH 7955/10049 ≈ 79%, Quad 4878/4967 ≈ 98%) and the **unit level (319)** (≈ 7–9% — serialized only). Copying Compass's 318 join into a client that doesn't write 318 yields a structurally-correct view with permanently blank tracking until 318 is backfilled. (NYCHH's pre-fix view pointed at the now-deleted record 41 = old IF-level/package bridge, i.e. it originally intended IF-level 317.)
 
 ## Change history
+- 2026-08-05 — Recorded that the 1.0 `App_Api_Toga2::syncItemFulfillmentFromNetsuite` full reconcile
+  now maintains **all three** IF bridges (317/318/319) and, when pruning units/items NetSuite dropped,
+  **deletes their bridge links first** because the bridge parent FKs are `RESTRICT` (no cascade) —
+  added the delete-order gotcha. (bala)
 - 2026-07-14 — **GroWrk** hit the bridge ACL gap (TRUE-79191): 403 EZ-1 on `item-fulfillment-tracking-numbers` made TOGa Supply's Pending Shipments list come back `isSuccess:false` (frontend showed the empty "Create your first shipment" state). GroWrk never got the fix that Prudential (2026-06-15) and Quad (2026-06-18a) already had. Added `Client_Growrk/2026-07-13a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql` (all 6 bridges 317-322, idempotent NOT-EXISTS guards, `slug='all'`/`sqlExpression='1'`, root logic group operator AND). Decision: kept Growrk-scoped for now (only client on Fulfill & Ship); shared `Client/` migration remains the long-term fix. (mhammontree)
 - 2026-07-09 — Noted that `Client_CompassCanada` is missing these bridge tables on **beta**, so a local
   reset from beta reintroduces the 17-table drift (1146 on SalesOrders load); fix locally with

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

@@ -27,6 +27,7 @@
 | [NetSuite Supporting-Record Webhook Importer (the reusable recipe)](features/netsuite-supporting-record-webhook-importer.md) | A single **repeatable recipe** for porting a legacy daily-pull NetSuite *supporting-record* importer (the lookup/dimension tables behind Forecast2 — Employees, | worker2/Worker/Netsuite/Employee.php, worker2/Worker/Netsuite/Account.php, worker2/Worker/Netsuite/Classification.php, worker2/Worker/Netsuite/Customer.php, worker2/Worker/Netsuite/Item.php, worker2/Worker/Netsuite.php, _underscore/Model/Forecast/Employee.php, _underscore/Model/Forecast/Account.php, _underscore/Model/Forecast/Classification.php, _underscore/Component/Forecast/Db/Db.php, test/@dave/test_employee_lifecycle.php, test/@dave/test_account_lifecycle.php, test/@dave/test_classification_lifecycle.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, worker/crons/toga2/forecast2/import_supporting_records.php |
 | [Background Email-Template Worker (_Worker_Notification_EmailTemplate)](features/notification-email-template.md) | `_Worker_Notification_EmailTemplate::Send(...)` dispatches a **stored, client-defined `EmailTemplates` row off-thread** as a background WorkerJob. | worker2/Worker/Notification/EmailTemplate.php, worker2/Worker/Client/True.php, _underscore/Model/Client/EmailTemplate.php |
 | [DB-Driven Notification (Internal) Email](features/notification-email.md) | Internal/notification emails (merge-conflict alerts, ops notices — anything system-generated, not client-facing transactional mail) are sent through one worker | worker2/Worker/Notification/Email.php, _underscore/Model/Client/EmailTemplate.php, dbchanges2/Client/2026-06-23a - EmailTemplateWrapper.sql, dbchanges2/Client_True/2026-06-23a - EmailTemplateWrapper.sql |
+| [NYCHH Asset-Tag Backfill (worker2)](features/nychh-asset-tag-backfill.md) | Keeps NYC Health & Hospitals (`Client_Nychh`) unit asset tags and MAC addresses synced from NetSuite. | worker2/Worker/Client/Nychh.php, worker2/Worker/Client/Nychh/AssetTagBackfill.php, worker/crons/toga2/netsuite/verify_fulfillment_asset_tag_sync_nychh.php, worker/crons/toga2/netsuite/backfill_all_asset_tags_from_netsuite_nychh.php |
 | [OneUptime push-metric monitors for 2.0 workers](features/oneuptime-worker2-monitoring.md) | A second, **OneUptime-reporting** monitoring pattern for the 2.0 worker2 tier, ported from the 1.0 `App_SystemMonitor_Compass` monitors. | worker2/Worker/Monitor/Compass.php, worker2/Worker/Client/Compass.php, worker2/composer.json, _underscore/Cloud.php, worker2/Worker/Monitor/Operations.php |
 | [Platform Cache Cleanup (_Worker_Platform_Cache — Clean + Truncate)](features/platform-cache-cleanup.md) | `_Worker_Platform_Cache` owns maintenance of the shared **Cache** cluster that backs api2's [multi-client data retrieval](../../api2/features/cross-client-data- | worker2/Worker/Platform/Cache.php, worker2/Controller/Index.php, worker2/_.php, dbchanges2/Core/2026-07-27a - PlatformCacheCleanCron.sql |
 | [Startech Webhook Handler (worker2)](features/startech-webhook-handler.md) | Receives inbound webhook events from Startech (Easeedesk) and creates or updates the corresponding ticket in TOGA 2.0. | worker2/Worker/Startech.php |

package/knowledge/2.0/apps/worker2/features/nychh-asset-tag-backfill.md

@@ -0,0 +1,99 @@
+---
+title: NYCHH Asset-Tag Backfill (worker2)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: nychh
+type: client-feature
+status: active
+updated: 2026-08-05
+owners: ["bala"]
+files:
+  - worker2/Worker/Client/Nychh.php
+  - worker2/Worker/Client/Nychh/AssetTagBackfill.php
+  - worker/crons/toga2/netsuite/verify_fulfillment_asset_tag_sync_nychh.php
+  - worker/crons/toga2/netsuite/backfill_all_asset_tags_from_netsuite_nychh.php
+related:
+  - ../../_underscore/features/netsuite-rest-client.md
+  - ../../../1.0/apps/library/features/toga2-api-client-and-bridge.md
+  - ../../../1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md
+  - creating-worker-actions.md
+  - ../../../clients/nychh/profile.md
+---
+
+## Summary
+
+Keeps NYC Health & Hospitals (`Client_Nychh`) unit asset tags and MAC addresses synced from
+NetSuite. In NetSuite the asset tag / MAC live on the **inventory-number (serial) record**, not
+the item-fulfillment transaction — so the regular per-client fulfillment sync does **not** pick up
+a tag that is added to the serial after the ItemShip is created (the sync's trigger is the
+fulfillment's `lastmodifieddate`, and a serial-only edit does not bump it). This backfill closes
+that gap: it reads every NYCHH unit's serial, asks NetSuite for the current tag/MAC, and writes
+them back.
+
+This is the **first NYCHH presence in worker2**. The write path is deliberately **direct-DB**
+(no api2), mirroring `_Worker_Client_Prudential_AssetImports`, to avoid the known beta
+worker2→api2 hard-crash (PHP 8.x, 500 with no trace).
+
+## Key files / entry points
+
+- **`worker2/Worker/Client/Nychh.php`** — the NYCHH client worker base. Its inherited
+  `initialize()` registers the `Client_Nychh` DB so any `_Model_Client_*` load resolves (see the
+  `DB_CLIENT` auto-registration gotcha in [creating-worker-actions](creating-worker-actions.md)).
+- **`worker2/Worker/Client/Nychh/AssetTagBackfill.php`** — the action.
+  Method: `Backfill(bool $dryRun = true, ?string $serialNumber = null): string`.
+  - Action path: `Client/Nychh/AssetTagBackfill/Backfill` → class
+    `_Worker_Client_Nychh_AssetTagBackfill`, method `Backfill`.
+  - Live cron: **`Core.CronJobs` id 44**, action `Client/Nychh/AssetTagBackfill/Backfill`.
+- **NetSuite access** — `_Component_Api_Netsuite` (2.0 `_underscore` REST client) SuiteQL. Creds
+  come from the worker2 `[netsuite]` ini section (`worker2/Config/<env>.ini`) — **location only,
+  never the values**; see [netsuite-rest-client](../../_underscore/features/netsuite-rest-client.md).
+
+## How it works
+
+1. Load all `Client_Nychh.Units` keyed by serial number.
+2. Ask NetSuite (SuiteQL over the `inventorynumber` table) for the asset tag + MAC of those
+   serials, **chunked 500 at a time**, filtering on the **native `inventorynumber` column**:
+   `WHERE inventorynumber IN ('serial1','serial2',…)`. Then `SELECT` the custom columns
+   `custitemnumber_asset_tag` / `custitemnumber_mac_address` and filter blanks in PHP.
+   > **Do not filter on the custom columns.** SuiteQL will `SELECT` them but a
+   > `WHERE custitemnumber_asset_tag IS NOT NULL` returns **0 rows with no error** — see the
+   > SuiteQL custom-field gotcha in
+   > [netsuite-rest-client](../../_underscore/features/netsuite-rest-client.md).
+3. **Never-blank** batch `UPDATE` of `Units.assetTag` / `Units.macAddress`: a value that is empty
+   in NetSuite never overwrites a populated TOGa value (NYCHH tags are sparse-then-growing, so a
+   blank NetSuite side is "not assigned yet", not "clear it").
+
+### Running it
+
+- `parameters` is spread as **named arguments** into `Backfill` (worker2 dispatch contract — see
+  [creating-worker-actions](creating-worker-actions.md)). It runs **dry by default**.
+- **Write:** pass `{"dryRun": false}`.
+- **Single-serial verification:** pass `serialNumber` to run one serial and print a
+  NetSuite-vs-TOGa comparison (no batch, useful for spot-checking a specific unit).
+
+### Verification & full-history backfill (1.0 companions)
+
+Two 1.0 `worker` scripts (run via PuTTY) back this up:
+
+- **`worker/crons/toga2/netsuite/verify_fulfillment_asset_tag_sync_nychh.php`** — read-only,
+  compares NetSuite vs TOGa per fulfillment to confirm the sync grabbed tags correctly.
+- **`worker/crons/toga2/netsuite/backfill_all_asset_tags_from_netsuite_nychh.php`** —
+  full-history SOAP per-serial backfill; `DRY_RUN` default, never-blank, resumable via a ledger
+  file.
+
+> **Reading the TOGa side must be flat + fully paginated.** api2 GET silently **truncates nested
+> collections** in a single response (a fulfillment's nested `itemFulfillmentItemUnits` came back
+> as 45 of 70), producing false verification results. Read flat, fully-paginated GETs and take
+> counts from `meta.totalRecordCount` — never from a single nested response. See the gotcha in
+> [App_Api_Toga2](../../../1.0/apps/library/features/toga2-api-client-and-bridge.md).
+
+## Change history
+- 2026-08-05 — BUILT the worker2 NYCHH asset-tag backfill (action
+  `Client/Nychh/AssetTagBackfill/Backfill`, cron `Core.CronJobs` id 44) — first NYCHH worker2
+  presence. Reads serials, queries NetSuite `inventorynumber` in 500-chunks by native serial
+  column (custom tag/MAC columns are SELECT-only, un-filterable), never-blank direct-DB UPDATEs of
+  `Units.assetTag`/`macAddress` (no api2, avoids the beta worker2→api2 crash; pattern from
+  `_Worker_Client_Prudential_AssetImports`). Added the 1.0 verification + full-history backfill
+  companion scripts. (bala)
+</content>

package/knowledge/INDEX.md

@@ -19,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 46 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 39 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 40 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 22 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 5 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 5 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)

package/knowledge/clients/nychh/profile.md

@@ -7,12 +7,15 @@ apps:
   - toga2-supply
   - toga25-supply
   - dbchanges2
+  - worker2
+  - worker
+  - library
 project: _Underscore
 client: nychh
 type: profile
 status: active
-updated: 2026-07-09
-owners: ["jcardinal", "apeterson"]
+updated: 2026-08-05
+owners: ["jcardinal", "apeterson", "bala"]
 files: []
 related:
   - ../../2.0/apps/_underscore/features/tracking-number-bridges.md
@@ -26,6 +29,8 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
 ## Platforms & data
 - **2.0:** `_underscore` backend, prod schema `Client_Nychh`. Item fulfillments, units, and
   tracking numbers follow the shared tracking-number bridge model.
+- **Worker tiers:** `worker2` (2.0) runs the NYCHH asset-tag backfill; `worker`/`library` (1.0)
+  run the NetSuite→TOGa Supply sync and the asset-tag verification/backfill diagnostics.
 
 ## Key features (this client)
 - Item-fulfillment table views (`item-fulfillments-for-sales-orders`,
@@ -33,6 +38,10 @@ table views. Client-specific DB change-sets live in `dbchanges2/Client_Nychh/`.
   re-rooted at `ItemFulfillmentItems` with item-level (record 318) tracking. See
   [Tracking-Number Bridge Migration](../../2.0/apps/_underscore/features/tracking-number-bridges.md)
   (Client variations + the TableView portability gotcha).
+- **Asset-tag backfill** (worker2, first NYCHH worker2 presence) — keeps `Units.assetTag`/
+  `macAddress` synced from the NetSuite serial (inventory-number) record, closing the gap where a
+  tag added after the ItemShip never bumps the fulfillment sync. See
+  [NYCHH Asset-Tag Backfill](../../2.0/apps/worker2/features/nychh-asset-tag-backfill.md).
 
 ## Notes
 - Tracking data: record 318 (item-level) is currently empty for this client; their tracking

package/knowledge/clients/rumcsi/profile.md

@@ -35,13 +35,19 @@ Richmond University Medical Center (**RUMCSI**) is a framework **1.0** client se
 - **TOGa View SAML.** `togaview/_/app/framework.php` has a RUMCSI-specific host branch that selects
   branding (`$_SESSION['stylePath']`) and the SAML login path — an unregistered togaview hostname
   falls through to default branding and skips SAML.
-- **⚠ Portal login is (probably) an unauthenticated `?hash=` link.** The rumcsi SAML `acs`
-  handler never populates `$_SESSION`, and the only working rumcsi session builder is a
-  `_/app/framework.php` block that authenticates on nothing but a base64-encoded email in
-  `?hash=`. RUMC login works in production, so that path may be load-bearing; it was
-  deliberately left in place pending confirmation of the real post-SSO redirect URL. Full
-  analysis and the proper fix: [TOGa View login
-  flows](../../1.0/apps/togaview/features/login-flows.md#open-security-item--rumcsi-hash-unauthenticated-account-takeover-deliberately-left-in-place).
+- **⚠ Portal login IS an unauthenticated `?hash=` magic link — and it is load-bearing.** The
+  rumcsi SAML `acs` handler never populates `$_SESSION`; the only working rumcsi session builder
+  is a `_/app/framework.php` block that authenticates on nothing but a base64-encoded email in
+  `?hash=` (no signature, nonce, or expiry). The routing evidence is firm: `framework.php:278`,
+  inside that block, is the **only** rumcsi route to `/enterprise_dashboard`, which is exactly
+  where a real production SSO login landed
+  (`rumcsi.togaview.agilantsolutions.com/enterprise_dashboard`), and togaview has **no** `?saml=`
+  handling, so the 2.0 SAML gateway is not involved. **Deleting the block breaks RUMC SSO into an
+  IdP redirect loop** — it must be signed or replaced by a completed `acs` handler, in
+  coordination with whoever generates the link (the generator is external to our repos and still
+  unidentified). Full analysis, both fix shapes, and the outstanding cold-login confirmation test:
+  [TOGa View login
+  flows](../../1.0/apps/togaview/features/login-flows.md#open-security-item--rumcsi-hash-is-the-live-production-sso-login-do-not-delete-it).
   Note also that the SAML branch is gated on `!inTestMode()`, so **test mode leaves rumcsi with
   no login path**.
 - **Hardcoded client-ID branching.** RUMCSI appears in TOGa Desk's hardcoded client-ID branching
@@ -49,6 +55,9 @@ Richmond University Medical Center (**RUMCSI**) is a framework **1.0** client se
 
 ## Change history
 
+- 2026-08-05 (later) — routing evidence confirms the `?hash=` path is the live SSO login (only
+  route to `/enterprise_dashboard`; no `?saml=` handling in togaview); deleting it would break
+  RUMC login into a redirect loop. (mhammontree)
 - 2026-08-05 — recorded the `?hash=` portal-login path as an open takeover risk left in place
   pending SSO confirmation, and the test-mode no-login-path gap (TRUE-80671). (mhammontree)
 - 2026-08-04 — Client profile created during the TRUE-80139 read-only review of the RUMCSI branded

package/package.json

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