toga-ai 1.0.40 → 1.0.42

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

@@ -5,3 +5,4 @@
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
 | [Carrier Shipping Labels (UPS/FedEx) & NetSuite Item Fulfillment](features/carrier-shipping-labels.md) | Backend mechanics behind TOGa Supply's Fulfill & Ship: buying a carrier label (UPS/FedEx), persisting it, and creating the NetSuite Item Fulfillment with tracki | _underscore/Model/Client/ItemFulfillment.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Trait/Netsuite/ItemFulfillment.php, _underscore/Trait/Netsuite/SalesOrder.php, _underscore/Component/Library/NetSuite/NetSuite.php, _underscore/Model/Client/TrackingNumber.php, _underscore/Model/Client/ShippingMethod.php, _underscore/Model.php, _underscore/Cloud.php |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql |
+| [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql |

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

@@ -0,0 +1,123 @@
+---
+title: Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-06-10
+owners: ["jcardinal"]
+files:
+  - _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php
+  - _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php
+  - _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php
+  - _underscore/Model/Client/ItemFulfillment.php
+  - _underscore/Model/Prudential/AdvanceShippingNotice.php
+  - _underscore/Model/Compass/AdvanceShippingNotice.php
+  - _underscore/Trait/Netsuite/ItemFulfillment.php
+  - api2/Component/Api/Cxml/Cxml.php
+  - dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql
+  - dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql
+related:
+  - recursive-item-fulfillments.md
+---
+
+## Summary
+
+Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`,
+`returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables across the ASN,
+Item Fulfillment (IF), and Item Receipt (IR) hierarchies. This migration moves all tracking
+into dedicated **`*_TrackingNumbers` bridge tables** (one consistent pattern per hierarchy
+level), so a record can carry multiple tracking numbers and the model is uniform. It also:
+
+- renames the ASN **`AdvanceShippingNoticeUnits`** table → **`AdvanceShippingNoticeItemUnits`**
+  (and its bridge + FK column `advanceShippingNoticeUnitId` → `advanceShippingNoticeItemUnitId`),
+- consolidates **`ItemFulfillmentPackages`** (header-level tracking) into
+  **`ItemFulfillments_TrackingNumbers`** and **drops the packages table**,
+- makes tracking a model concept submitted/read **as an inherent child of the parent record**
+  (not a scalar field).
+
+## The bridge pattern
+
+Each hierarchy level gets a bridge keyed to its parent plus `trackingNumberId`
+(+ `returnTrackingNumberId` on ASN and IF bridges; IR has no returns):
+
+| Level | Bridge table | Core Record id | Route (inherent-child key) |
+|---|---|---|---|
+| ASN | AdvanceShippingNotices_TrackingNumbers | 218 | advance-shipping-notice-tracking-numbers |
+| ASN item | AdvanceShippingNoticeItems_TrackingNumbers | 217 | advance-shipping-notice-item-tracking-numbers |
+| ASN unit | AdvanceShippingNoticeItemUnits_TrackingNumbers | 216 (renamed) | advance-shipping-notice-item-unit-tracking-numbers |
+| IF | ItemFulfillments_TrackingNumbers | 317 (new) | item-fulfillment-tracking-numbers |
+| IF item | ItemFulfillmentItems_TrackingNumbers | 318 (new) | item-fulfillment-item-tracking-numbers |
+| IF item unit | ItemFulfillmentItemUnits_TrackingNumbers | 319 (new) | item-fulfillment-item-unit-tracking-numbers |
+| IR | ItemReceipts_TrackingNumbers | 320 (new) | item-receipt-tracking-numbers |
+| IR item | ItemReceiptItems_TrackingNumbers | 321 (new) | item-receipt-item-tracking-numbers |
+| IR item unit | ItemReceiptItemUnits_TrackingNumbers | 322 (new) | item-receipt-item-unit-tracking-numbers |
+
+All bridges are registered as **`InherentRecordChildren`** of their parent record, so the
+engine derives the payload key from the bridge route (kebab→camel) — e.g. an ASN unit's
+tracking is submitted as `advanceShippingNoticeItemUnitTrackingNumbers: [{ trackingNumber: {...},
+returnTrackingNumber: {...} }]`, and an IFIU's as `itemFulfillmentItemUnitTrackingNumbers`.
+
+## Key files / entry points
+
+- **Bridge models** — `Model/Client/<Parent>/TrackingNumber.php` (e.g. `ItemFulfillmentItemUnits/TrackingNumber.php`).
+  The renamed ASN unit model is `Model/Client/AdvanceShippingNoticeItemUnit.php`; the old
+  `AdvanceShippingNoticeUnit.php` + `AdvanceShippingNoticeUnits/TrackingNumber.php` were deleted.
+- **Recursive feature** — `Model/Client/ItemFulfillment.php`: `reconcileUpstreamUnits` and
+  `reconcileUpstreamPackages` now read/write the bridges (POST `/item-fulfillment-item-unit-tracking-numbers`
+  and `/item-fulfillment-tracking-numbers`); unit deletes cascade to the inherent-child bridge rows.
+  The FedEx/shipping-label methods read header tracking from `ItemFulfillments_TrackingNumbers`.
+- **Prudential interceptor** — `Model/Prudential/AdvanceShippingNotice.php::prePost` (see the
+  Prudential client doc).
+- **cXML inbound** — `api2/Component/Api/Cxml/Cxml.php` emits the new key + bridge-child tracking.
+- **DB** — `dbchanges2/Core/...` (records/fields/ACL/inherent-children, record-41 teardown),
+  `dbchanges2/Client/...` (renames, bridges, migrations, ACL) split into an additions file and a
+  companion `..._DROPS.sql` for the column/table drops to run after confirmation.
+
+## Data model
+
+- New bridges: `id, uuid, <parentFk>, trackingNumberId (NULL), [returnTrackingNumberId (NULL)]`,
+  `InnoDB / utf8mb4_unicode_ci`, `UNIQUE(uuid)`, `UNIQUE(<parentFk>, trackingNumberId)`, FKs to
+  the parent + `TrackingNumbers`.
+- Dropped (in the DROPS file): `AdvanceShippingNoticeItemUnits.trackingNumberId/returnTrackingNumberId`,
+  `ItemFulfillmentItemUnits.trackingNumberId`, `ItemReceiptItems.trackingNumberId`,
+  `ItemReceiptItemUnits.trackingNumberId`, and the entire `ItemFulfillmentPackages` table.
+- Core: Records 61 (unit) + 216 (unit bridge) renamed; new Records 317–322 + RecordFields 2171–2200;
+  `returnTrackingNumberId` RecordFields added to 216/217/218; dropped RecordFields 334/652/1431/1576/1577;
+  record 41 (item-fulfillment-packages) fully removed. Label settings (`DefaultRecordFieldSettings`)
+  and `Records.labelRecordFieldId` are **repointed** from dropped fields to the new bridge fields.
+
+## Client variations
+
+- **Compass (Client_Compass / compass-usa):** ASN→IF auto-creation (`Model/Compass/AdvanceShippingNotice.php`)
+  posts unit tracking + header tracking via the bridge routes; `Model/Compass/SalesOrder.php::_trackingNumbers`
+  reads through the bridges. The `item-fulfillments-for-sales-order-items` TableView was rebuilt
+  (see the compass-usa client doc).
+- **Prudential (Client_Prudential):** Dell posts the legacy `advanceShippingNoticeUnits` key with flat
+  tracking — a PRE/POST interceptor rewrites it (see the prudential client doc).
+- **NetSuite-integrated clients:** `Trait/Netsuite/ItemFulfillment.php` now reads
+  `itemFulfillmentTrackingNumbers` and posts `/item-fulfillment-tracking-numbers`. The 1.0 library
+  `App_Api_Toga2` (`library/app/api/toga2.php`) got the same change for the worker tier.
+
+## Gotchas / known issues
+
+- **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.
+- **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
+  `TableViews.sortPrimaryTableViewFieldId` (null it first, re-point after); self-referencing `INSERT … NOT EXISTS`
+  on the target table errors 1093 (use a derived table); and orphaned/dangling `trackingNumberId` values
+  fail the bridge FK 1452 (join `TrackingNumbers` so orphans become NULL / are skipped).
+- **UUIDs in SQL:** generated with `RANDOM_BYTES()` (MySQL 8) — never MySQL `UUID()` (per 2.0 standard).
+- **Dropped FK constraint names vary per client** — drop them dynamically via `INFORMATION_SCHEMA` + PREPARE.
+- **Deploy coupling:** renames are NOT backward compatible — apply the DB migration and deploy
+  `_underscore` + `api2` + `worker` + `library` together. Run the additions/migrations DB file first;
+  run the companion `..._DROPS.sql` (and the Core deletes) only after the bridges + app are confirmed.
+
+## Related docs
+- Recursive Item Fulfillment feature (the upstream-sync engine this migration reworked).
+- compass-usa: ASN→Item Fulfillment, and the Item Fulfillment tracking TableView.
+- prudential: Dell ASN units interceptor.

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

@@ -6,3 +6,4 @@
 | [ClickUp Project & Opportunity Multi-List Routing](features/clickup-project-routing.md) | Routes ClickUp tasks into the correct **secondary multi-list memberships** based on their custom-field values, via the `clickup` webhook. | worker2/Worker/Clickup/Project.php, worker2/Worker/Clickup.php |
 | [Creating Worker Actions](features/creating-worker-actions.md) | How to add a new callable Worker action — a PHP class whose `public static` methods are invoked as background jobs (via webhook, cron, or `_Worker::runTask()`). | worker2/Worker/, worker2/Controller/Index.php, _underscore/Worker.php |
 | [Elite Freshservice Sync (worker2)](features/elite-freshservice-sync.md) | `_Worker_Elite` processes Freshservice webhook events and syncs them into TOGA 2. | worker2/Worker/Elite.php, worker2/Config/dev-kmaramreddy-laptop.ini |
+| [Monitoring Framework (Orchestrator + Child Monitors)](features/monitoring-framework.md) | A unified, DB-driven monitoring framework for business-critical data flows (Compass POs, Prudential asset imports, AIG closed claims, …). | worker2/Worker/Monitor.php, worker2/Worker/Monitors/, worker2/Worker/Notification/Email.php, dbchanges2/Core/2026-05-21 - Monitors.sql |

package/knowledge/2.0/apps/worker2/features/monitoring-framework.md

@@ -0,0 +1,183 @@
+---
+title: Monitoring Framework (Orchestrator + Child Monitors)
+framework: "2.0"
+repo: worker2
+project: Worker
+client: shared
+type: feature
+status: active
+updated: 2026-06-10
+owners: [mhammontree]
+files:
+  - worker2/Worker/Monitor.php
+  - worker2/Worker/Monitors/
+  - worker2/Worker/Notification/Email.php
+  - dbchanges2/Core/2026-05-21 - Monitors.sql
+related:
+  - ../architecture.md
+  - ./creating-worker-actions.md
+  - ../../dbchanges2/architecture.md
+---
+
+## Summary
+
+A unified, DB-driven monitoring framework for business-critical data flows (Compass POs,
+Prudential asset imports, AIG closed claims, …). One orchestrator applies consistent
+anti-flap logic and notification rules to any registered "is X healthy?" check. Replaces
+scattered/ad-hoc monitoring where failures surfaced only when a client complained.
+
+**Status (2026-06-10):** v1.0 framework + orchestrator landed; **first child monitor
+pending**. Migration applied to local Core_2 only — **not yet on staging/production Core**
+(coordinate before merge). Dashboard/acknowledgment layer under discussion (see Pending
+scope).
+
+Design principles: async isolation (one cron per monitor — a slow monitor can't block
+others) · anti-flap on the recovery side only (N consecutive OKs before declaring
+recovery) · immediate alert on first failure, throttled reminders, one recovery email per
+incident · dumb-and-light children (all state/escalation/email logic lives once in the
+orchestrator) · runtime config in the `Core.Monitors` table (no redeploy).
+
+## Key files / entry points
+
+| File | Purpose |
+|---|---|
+| `worker2/Worker/Monitor.php` | Orchestrator — `abstract class _Worker_Monitor`, action route `Monitor/Run` |
+| `worker2/Worker/Monitors/<Name>.php` | Child classes `_Worker_Monitors_<Name>`, one per monitor |
+| `worker2/Worker/Notification/Email.php` | Reused `_Worker_Notification_Email::Send` for all notification mail |
+| `dbchanges2/Core/2026-05-21 - Monitors.sql` | `Core.Monitors` table definition + INSERT templates |
+
+Reused with **no changes**: `Core.CronJobs`, `Core.WorkerJobs`, the `WorkerCronScheduler`
+Lambda, the EB worker tier + SQS delivery (see [worker2 architecture](../architecture.md)).
+
+## How it works
+
+One `Core.CronJobs` row per monitor (`action = 'Monitor/Run'`, `parameters =
+{"monitorId": N}`, schedule evaluated in **Central** time). Each tick, the orchestrator:
+
+1. Fetches the `Core.Monitors` row by `monitorId` (not found → return message, no writes).
+2. Guards `isActive` — if 0, returns early; no child invocation, no mail.
+3. Invokes the child: `class_exists` / `method_exists` checks, then `$phpClass::Run()`
+   inside try/catch. **Any `Throwable` becomes `{isOk: false}`** with the exception
+   message — a child can never crash the orchestrator. The return must be an object with
+   `isOk` and `message`; anything else is treated as failure.
+4. Runs the state machine (below) to compute new state, counter, and notification.
+5. Sends mail if needed via `_Worker_Notification_Email::Send` with
+   `clientIdentifier: 'Core'` (infrastructure mail, never client-scoped).
+6. Persists one UPDATE: `state`, `consecutiveOkCount`, `lastRunDt`, `lastResultMessage`,
+   plus `lastNotificationDt`/`lastNotificationType` when a notification was sent.
+7. Returns a one-line summary that lands in `WorkerJobs` for diagnostics.
+
+Uses `_Query($sql, _underscore::DB_CORE)` and `_Database::escape()` for interpolated values.
+
+### State machine (the agreed contract)
+
+| Previous | Current | New state | Counter | Notification |
+|---|---|---|---|---|
+| ok | ok | ok | reset to 0 | none |
+| ok | alert | **alert** | reset to 0 | **alert** — always, immediate |
+| alert | alert | alert | unchanged (0) | **reminder** — only if `reminderFrequencyMinutes` elapsed since `lastNotificationDt` |
+| alert | ok | alert until counter hits threshold | +1 | **recovery** — only when `consecutiveOkCount >= requiredConsecutiveOks`; on send, flip to ok and reset counter |
+
+Three **intentional product decisions** (deviations from the original meeting summary —
+if you change any, update the plan doc and announce in #engineering):
+1. No anti-flap on the alarm side — first failure alerts immediately.
+2. Recovery fires only on an actual alert → ok transition (the meeting's "ok→ok sends
+   recovery" branch was folded out).
+3. Recovery is **not** gated on the reminder window — gating could swallow the
+   "all clear" email entirely.
+
+Reminder-window math uses PHP server time vs `lastNotificationDt` written via DB `NOW()`
+— consistent on a single DB server, **not explicitly UTC**; revisit if a cross-region DB
+is ever introduced.
+
+### Notifications
+
+Subjects: `[Monitor ALERT|REMINDER|RECOVERED] <monitor name>`. Plain-text body with
+monitor name, state, notification type, timestamp, and the child's message verbatim.
+From `donotreply@goagilant.com`; recipients parsed from `Monitors.peopleToNotify` (JSON
+array of emails — empty array means no mail sent, no error raised).
+
+## Data model
+
+### `Core.Monitors` (new)
+
+| Column | Type | Purpose |
+|---|---|---|
+| `id` / `uuid` | INT UNSIGNED PK / char(36) UNIQUE | Standard identifiers |
+| `isActive` | TINYINT default 1 | 0 = orchestrator returns early |
+| `dtCreated` | DATETIME | Record create time |
+| `name` | VARCHAR(255) | Human-readable; appears in email subjects |
+| `phpClass` | VARCHAR(255) | Child class, e.g. `_Worker_Monitors_Compass` |
+| `state` | ENUM('ok','alert') default 'ok' | **Confirmed** current state |
+| `consecutiveOkCount` | INT UNSIGNED default 0 | Anti-flap counter (alert→ok only) |
+| `requiredConsecutiveOks` | TINYINT UNSIGNED default 2 | Threshold to flip alert→ok |
+| `reminderFrequencyMinutes` | SMALLINT UNSIGNED default 60 | Reminder cadence while in alert |
+| `peopleToNotify` | JSON | Array of email addresses |
+| `lastRunDt` / `lastResultMessage` | DATETIME / TEXT | Last run + last child message (or exception text) |
+| `lastNotificationDt` / `lastNotificationType` | DATETIME / ENUM('alert','reminder','recovery') | Most recent notification |
+
+Index `Monitors_isActive_IDX (isActive)`. `Core.CronJobs` reused as-is — one row per monitor.
+
+## Child monitor contract
+
+- File `worker2/Worker/Monitors/<Name>.php`, class `abstract class _Worker_Monitors_<Name>`
+  with `public static function Run(): object` returning
+  `(object)['isOk' => bool, 'message' => string]` — matches the worker2 action convention.
+- `Run()` takes **no parameters**; all per-monitor config lives in the `Monitors` row.
+- **Don't**: send notifications, write to `Monitors`, implement escalation, or wrap
+  everything in try/catch (the orchestrator catches all `Throwable`s — bubbling up is the
+  simplest way to fail loudly).
+- **Do**: check exactly one signal per monitor; put actionable context in `message`
+  (recipients see it verbatim); register any non-Core DB connection inline at the top of
+  `Run()` — the framework does **not** call `initialize()` on child monitors.
+
+### Adding a new monitor (runbook)
+
+1. Write the child class (one check, returns `{isOk, message}`).
+2. INSERT the `Core.Monitors` row (uuid, name, phpClass, thresholds, peopleToNotify).
+3. INSERT the `Core.CronJobs` row (`action = 'Monitor/Run'`,
+   `parameters = JSON_OBJECT('monitorId', <id>)`).
+4. Verify end-to-end in dev (8-step checklist: migration sanity, cron registration,
+   first-failure alert, reminder cadence, anti-flap recovery, exception path, inactive
+   monitor, missing class — all must pass before production).
+5. Deploy class to staging+production worker2; apply the two INSERTs to each Core.
+
+No Lambda, SQS, or orchestrator changes needed per monitor.
+
+### Operational notes
+
+- Force a recheck: set `lastRunDt = NULL`, or POST `{"action":"Monitor/Run","parameters":{"monitorId":N}}` to the worker2 test endpoint (debug path, bypasses WorkerJobs).
+- Pause a monitor: `isActive = 0` (cron row can stay active). Pause email only: `peopleToNotify = JSON_ARRAY()`.
+- Manual state reset: clear `state`/`consecutiveOkCount`/`lastNotificationDt`/`lastNotificationType` — sparingly; the state machine self-corrects.
+
+## Client variations
+
+None — the framework is shared Core infrastructure. Individual monitors target specific
+clients' data flows (Compass, Prudential, AIG, …) but live as separate child classes.
+
+## Gotchas / known issues
+
+- **First child monitor not yet built** — `worker2/Worker/Monitors/` does not exist yet
+  (as of 2026-06-10).
+- **Migration not applied to staging/production Core** — only local Core_2. Coordinate
+  before merge.
+- `worker2/MONITORING_PLAN.md` is referenced by the design doc but **missing on disk** —
+  stale reference to resolve.
+- Child return value must be an **object** with both `isOk` and `message`; a bare array
+  or missing property is treated as failure by design.
+- Reminder math is server-time based, not UTC — see state-machine section.
+
+## Pending scope (NOT implemented)
+
+- **Dashboard + acknowledgments** — ack columns on `Monitors` (or a history table),
+  reminder gate becomes "elapsed AND not acknowledged", recovery clears the ack. Open
+  questions: ack survival across flap-back, auto-expiry, which auth system owns dashboard
+  identity. Owner: mhammontree, pending team discussion.
+- Slack / SMS / PagerDuty (email-only today) · `MonitorRuns` history table ·
+  HTML email + dashboard deep-links · anti-flap on the alarm side.
+
+## Related docs
+
+- [worker2 architecture](../architecture.md) — cron/WorkerJobs pipeline the orchestrator rides on
+- [Creating Worker Actions](./creating-worker-actions.md) — the action class/method conventions child monitors follow
+- [dbchanges2 architecture](../../dbchanges2/architecture.md) — migration naming/ordering rules for the Monitors table change

package/knowledge/INDEX.md

@@ -9,8 +9,8 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 3 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 4 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 4 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **worker2** (Worker) — 5 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 1 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 1 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 2 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
@@ -21,4 +21,5 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **compass-usa** → [clients/compass-usa/INDEX.md](clients/compass-usa/INDEX.md)
 - **elite** → [clients/elite/INDEX.md](clients/elite/INDEX.md)
 - **nycdoe** → [clients/nycdoe/INDEX.md](clients/nycdoe/INDEX.md)
+- **prudential** → [clients/prudential/INDEX.md](clients/prudential/INDEX.md)
 

package/knowledge/clients/compass-usa/INDEX.md

@@ -3,4 +3,5 @@
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
 | [Compass ASN → ItemFulfillment Auto-Creation](features/asn-to-item-fulfillment.md) | 2.0 | For Compass USA, posting an AdvanceShippingNotice (ASN) auto-creates the ItemFulfillment (IF) on the upstream SalesOrder. | _underscore/Model/Compass/AdvanceShippingNotice.php |
+| [Compass: Item Fulfillments for Sales Order Items TableView (tracking via bridge)](features/item-fulfillment-tracking-tableview.md) | 2.0 | The Compass TableView `item-fulfillments-for-sales-order-items` (`TableViews.id = 13` in Client_Compass) was rebuilt as part of the tracking-number bridge migra | dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql |
 | [Compass USA](profile.md) | 2.0 | Compass USA is a TOGA client running a multi-tier supply-chain commerce operation. |  |

package/knowledge/clients/compass-usa/features/item-fulfillment-tracking-tableview.md

@@ -0,0 +1,46 @@
+---
+title: "Compass: Item Fulfillments for Sales Order Items TableView (tracking via bridge)"
+framework: "2.0"
+project: _Underscore
+client: compass-usa
+type: client-feature
+status: active
+updated: 2026-06-10
+owners: ["jcardinal"]
+files:
+  - dbchanges2/Client_Compass/2026-06-10 - ItemFulfillmentsForSalesOrderItemsTableView.sql
+related:
+  - ../../../2.0/apps/_underscore/features/tracking-number-bridges.md
+---
+
+## Summary
+
+The Compass TableView `item-fulfillments-for-sales-order-items` (`TableViews.id = 13` in
+Client_Compass) was rebuilt as part of the tracking-number bridge migration. It was rooted at
+**Units** with INNER joins (so non-serialized items with no unit never appeared) and sourced the
+outbound tracking number from the now-dropped `ItemFulfillmentItemUnits.trackingNumberId`.
+
+## How it works (new definition)
+
+- **Base record re-rooted** to `ItemFulfillmentItems` (record 29).
+- Joins: INNER `SalesOrderItems`; **OUTER** `ItemFulfillmentItemUnits` (so items without a
+  serialized unit still return); OUTER `Units`; OUTER the new `ItemFulfillmentItemUnits_TrackingNumbers`
+  bridge (record 319) → OUTER `TrackingNumbers` → OUTER `ShippingCarriers`.
+- Columns, in order: **Sales Order Line Number, Quantity Fulfilled (new — `ItemFulfillmentItems.quantity`),
+  Outbound Tracking #, Carrier, Serial #, Asset Tag.**
+- Default sort (`TableViews.sortPrimaryTableViewFieldId`) re-pointed to the line-number field.
+
+## Gotchas / known issues
+
+- Tracking is sourced through the bridge join (`ItemFulfillmentItemUnits_TrackingNumbers.trackingNumberId`),
+  NOT the dropped column. The bridge record/fields (319 / 2183 itemFulfillmentItemUnitId / 2184
+  trackingNumberId) come from the Core migration and must exist before this file runs.
+- `TableViews.sortPrimaryTableViewFieldId` is a FK to `TableViewFields`; it must be set NULL before the
+  old fields are deleted, then re-pointed (via a multi-table UPDATE, not a self-subquery, to avoid 1093).
+- `TableViewFields` must be deleted before `TableViewJoins` (`tableViewJoinId` FK).
+
+## Client variations
+This is Compass-only. The underlying bridge model is shared (see the _underscore feature doc).
+
+## Related docs
+- 2.0 _underscore: Tracking-Number Bridge Migration.

package/knowledge/clients/prudential/INDEX.md

@@ -0,0 +1,6 @@
+# Client: prudential
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Prudential: Dell ASN units PRE/POST interceptor (legacy key + flat tracking)](features/dell-asn-units-interceptor.md) | 2.0 | After the tracking-number bridge migration, the ASN unit route was renamed (`advance-shipping-notice-units` → `advance-shipping-notice-item-units`), so the inhe | _underscore/Model/Prudential/AdvanceShippingNotice.php, dbchanges2/Client_Prudential/2026-06-10 - AsnUnitsInterceptor.sql |
+| [Prudential](profile.md) | 2.0 | Prudential is a TOGA client whose device-fulfillment flow is driven by **Dell** via the Dell API (`Client_Prudential.Apis.id = 2`). |  |

package/knowledge/clients/prudential/features/dell-asn-units-interceptor.md

@@ -0,0 +1,51 @@
+---
+title: "Prudential: Dell ASN units PRE/POST interceptor (legacy key + flat tracking)"
+framework: "2.0"
+project: _Underscore
+client: prudential
+type: client-feature
+status: active
+updated: 2026-06-10
+owners: ["jcardinal"]
+files:
+  - _underscore/Model/Prudential/AdvanceShippingNotice.php
+  - dbchanges2/Client_Prudential/2026-06-10 - AsnUnitsInterceptor.sql
+related:
+  - ../../../2.0/apps/_underscore/features/tracking-number-bridges.md
+---
+
+## Summary
+
+After the tracking-number bridge migration, the ASN unit route was renamed
+(`advance-shipping-notice-units` → `advance-shipping-notice-item-units`), so the inherent-child
+key became `advanceShippingNoticeItemUnits`, and unit tracking now lives in the bridge child
+`advanceShippingNoticeItemUnitTrackingNumbers` (the scalar `trackingNumber`/`returnTrackingNumber`
+fields on the unit were dropped). **Dell will not change their payload**, so a Prudential-only
+interceptor translates it on the way in.
+
+## How it works
+
+- **`Model/Prudential/AdvanceShippingNotice.php::prePost(&$api, &$payload)`** — for each
+  `$payload->advanceShippingNoticeItems[]`: renames the legacy `advanceShippingNoticeUnits` key to
+  `advanceShippingNoticeItemUnits`, and lifts each unit's flat `trackingNumber` / `returnTrackingNumber`
+  into a single `advanceShippingNoticeItemUnitTrackingNumbers` bridge-child row, removing the flat fields.
+- **Registration** — `Client_Prudential.ApiPayloadInterceptors` row: `recordId = 55`
+  (advance-shipping-notices), `prePostProcessing = 'PRE'`, `httpMethod = 'POST'`, `apiId = 2` (Dell),
+  `isActive = 1`. The engine resolves `_Model_Client_AdvanceShippingNotice` → `_Model_Prudential_AdvanceShippingNotice`
+  by client identifier; **both** the DB interceptor row AND the model method are required for it to fire.
+
+## Inbound payload (Dell, unchanged)
+```
+advanceShippingNoticeItems: [ { quantity, advanceShippingNoticeUnits: [
+    { trackingNumber:{number}, returnTrackingNumber:{number}, unit:{serialNumber} } ] } ]
+```
+The interceptor rewrites each item to `advanceShippingNoticeItemUnits` with the tracking moved into
+`advanceShippingNoticeItemUnitTrackingNumbers`.
+
+## Gotchas
+- Scoped to `apiId = 2` so other (internal) Prudential callers — which already send the new shape —
+  are not double-transformed.
+- DB change lives in `dbchanges2/Client_Prudential/`.
+
+## Related docs
+- 2.0 _underscore: Tracking-Number Bridge Migration.

package/knowledge/clients/prudential/profile.md

@@ -0,0 +1,34 @@
+---
+title: Prudential
+framework: "2.0"
+project: _Underscore
+client: prudential
+type: profile
+status: active
+updated: 2026-06-10
+owners: ["jcardinal"]
+files: []
+related:
+  - features/dell-asn-units-interceptor.md
+---
+
+## Summary
+Prudential is a TOGA client whose device-fulfillment flow is driven by **Dell** via the Dell
+API (`Client_Prudential.Apis.id = 2`). Dell posts Advance Shipping Notices (with tracking and
+return-tracking per unit) into the 2.0 platform (DB `Client_Prudential`); the 1.0 worker tier
+(`crons/toga2/prudential/`) handles NetSuite sync, ServiceNow (RITM) close/ship updates, and
+order-status transmissions.
+
+## Integrations
+- **Inbound:** Dell API → POST `/v2/advance-shipping-notices` (creates ASNs + units + tracking).
+- **Outbound (worker crons):** `transmissions_to_netsuite.php`, `transmit_ordershipped_updates_prudential.php`,
+  `transmit_closecomplete_updates_prudential.php`, `transmit_order_delivered_updates_from_fedex_toga2.php`,
+  `update_tracking_number_from_netsuite_to_toga.php`, `manually_insert_ASN.php`.
+
+## Gotchas
+- Dell will not change their payload shape — see the Dell ASN units interceptor feature doc for the
+  PRE/POST translation that keeps their feed working after the tracking-number bridge migration.
+
+## Related docs
+- Dell ASN units interceptor.
+- 2.0 _underscore: Tracking-Number Bridge Migration.

package/package.json

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