toga-ai 1.0.232 → 1.0.234

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

@@ -7,6 +7,7 @@
 | [Assortment Name Translation (AssortmentTranslations sidecar)](features/assortment-name-translation.md) | Serves Assortment (product-grouping) **names** in multiple languages by adding a per-language **sidecar** table `AssortmentTranslations`, reusing the platform's | _underscore/Model/Client/AssortmentTranslation.php, dbchanges2/Client/2026-06-26a - AssortmentTranslations.sql, dbchanges2/Core/2026-06-26a - AssortmentTranslationsRecord.sql, dbchanges2/Client/2026-06-26b - AssortmentTranslationsAcl.sql |
 | [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/Model/Client/ItemFulfillments/TrackingNumber.php, _underscore/Component/Library/LabelPdf/LabelPdf.php, _underscore/Component/Library/Carriers/Ups/Ups.php, _underscore/Component/Library/Carriers/Fedex/Fedex.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 |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
+| [Record-Changed Event Publishing (_Event::publish to SQS)](features/event-publish-sqs.md) | `_Event::publish()` (in `_underscore/Event.php`) is the PHP side of the real-time event pipeline. | _underscore/Event.php |
 | [Forecast.Sales NetSuite import engine (real-time webhook)](features/forecast-sale-import.md) | Real-time importer that takes a NetSuite **sale** record and writes its lines into `Forecast.Sales` (the Forecast2 revenue table). | _underscore/Component/Forecast/SaleImport/SaleImport.php, _underscore/Component/Forecast/Db/Db.php, _underscore/Component/Api/Netsuite/Netsuite.php, worker2/Worker/Netsuite/Invoice.php, worker2/Worker/Netsuite/CashSale.php, worker2/Worker/Netsuite/CreditMemo.php, worker2/Worker/Netsuite/CashRefund.php, worker2/Worker/Netsuite/JournalEntry.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Worker/Netsuite/SalesOrder.php, dbchanges2/Forecast/2026-06-26a - Add journalEntry to Sales transaction type enum.sql, test/@dave/test_invoice_lifecycle.php, test/@dave/test_je_lifecycle.php, test/@dave/test_creditmemo_lifecycle.php, test/@dave/test_cashsale_lifecycle.php, test/@dave/test_cashrefund_lifecycle.php, test/@dave/test_fetchrecord_routes.php, test/@dave/verify_je_classification.php, test/@dave/probe_je_accounts.php, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/dev_ue_api_msg_queue_enqueue.js |
 | [_Model magic-field access (__get without __isset)](features/model-magic-field-access.md) | `_Model` exposes DB columns as "magic" properties via `__get()`, but it defines **no** `__isset()`. | _underscore/Model/Core/Model.php |
 | [NetSuite REST Client (_Component_Api_Netsuite) — record writes & SuiteQL](features/netsuite-rest-client.md) | `_Component_Api_Netsuite` is the **2.0 `_underscore` NetSuite REST client** — the shared primitive every worker2/api2 NetSuite caller uses for record GETs, Suit | _underscore/Component/Api/Netsuite/Netsuite.php |

package/knowledge/2.0/apps/_underscore/features/event-publish-sqs.md

@@ -0,0 +1,60 @@
+---
+title: Record-Changed Event Publishing (_Event::publish to SQS)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-06-29
+owners: [rgirish]
+files:
+  - _underscore/Event.php
+related:
+  - ../../../../standalone/apps/websocket/features/sqs-fanout.md
+---
+
+## What it is
+
+`_Event::publish()` (in `_underscore/Event.php`) is the PHP side of the real-time event
+pipeline. After a successful V2 write (POST/PUT/PATCH), it publishes a single JSON message
+to the `toga-events` SQS queue describing what changed. The `websocket` standalone server
+consumes that queue and fans out `record:changed` to browsers. The whole call is wrapped in
+a `try/catch (\Throwable)` so an SQS failure logs but never blocks or errors the API
+response.
+
+## How it works
+
+`publish(object &$api, string $httpMethod, array $routeVars)`:
+
+1. Reads `aws_event_queue_url` / `aws_event_queue_region` from `_Config::cloud()`; returns
+   early if no queue URL is configured.
+2. Determines the affected record's `recordRoute`, `recordId`, `uuid`.
+3. Derives `parentRoute` / `parentUuid` from `$routeVars` when the URL is a nested resource
+   (`count($routeVars) >= 3` → `parentRoute = $routeVars[0]`, `parentUuid = $routeVars[1]`).
+4. JSON-encodes `{ clientId, clientUuid, recordRoute, recordId, uuid, httpMethod,
+   parentRoute, parentUuid, dtEvent }` and enqueues via `_Cloud::addSqsMessage()`.
+
+SQS credentials come from `_Config::cloud('aws_event_queue_access_key_id' /
+'..._secret_access_key')` — values live in config/cloud, never in code or this doc.
+
+## Gotchas
+
+- **`recordRoute` must come from `$routeVars[0]`, not `$api->record->route`.** Post-`POST`
+  interceptors can swap `$api->record` to a *different* model before `publish()` runs (e.g.
+  `service-requests`' `postPost` switches `$api->record` to the `service-request-bundles`
+  model), so `$api->record->route` would point at the wrong route. Read the original URL
+  segment `$routeVars[0]`, falling back to `$api->record->route` only when `routeVars` is
+  empty.
+- **`$api->response->data` is a PHP array, not a stdClass object.** `processRoutePairs()`
+  in V2.php returns e.g. `['serviceRequests' => $outData]`. Using object access
+  (`$data->{$topKey}`) on it silently returns null, so `uuid`/`recordId` were always null in
+  published events. Cast first: `$data = (array) $api->response->data;` then
+  `$topRecord = (object) $data[array_key_first($data)];` before reading `->id` / `->uuid`.
+
+## Change history
+- 2026-06-29 — Fixed `recordRoute` to read `$routeVars[0]` (authoritative URL route) because
+  post-interceptors can mutate `$api->record` to a different model before publish. (rgirish)
+- 2026-06-29 — Fixed null `uuid`/`recordId` in SQS events: response data is a PHP array, so
+  cast `(array)` before `array_key_first()` and `(object)` the top record before property
+  access (was using object access on an array → silent null). (rgirish)

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

@@ -12,7 +12,7 @@
 | [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 |
 | [Etilize Catalog Item Import & Refresh](features/etilize-catalog-item-import.md) | Client-generic catalog onboarding from an S3 CSV plus an Etilize re-pull. | worker2/Worker/Etilize/Items.php |
 | [Etilize Item Translation Import](features/etilize-item-translation-import.md) | The abstract worker class `_Worker_Etilize_ItemTranslations` imports **non-English** item text from Etilize into the client's `ItemTranslations` table. | worker2/Worker/Etilize/ItemTranslations.php |
-| [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 |
+| [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/Monitors/RateEntitlement.php, worker2/Worker/Notification/Email.php, worker2/Worker/Rate.php, dbchanges2/Core/2026-05-21 - Monitors.sql, dbchanges2/Core/2026-06-29a - Rate Entitlement Contract Monitor.sql |
 | [NetSuite → TOGA Opportunity Sync (API Message Queue + worker2 webhook)](features/netsuite-opportunity-sync.md) | Outbound sync from NetSuite to TOGA for the record types the Forecast2 importer pulls (opportunities first; sales/items/etc. | worker2/Worker/Netsuite.php, worker2/Worker/Netsuite/Opportunity.php, worker2/Controller/Index.php, _underscore/Worker.php, test/@dave/NetSuite/api-message-queue/lib_amq_queue.js, test/@dave/NetSuite/api-message-queue/ue_api_msg_queue_enqueue.js, test/@dave/NetSuite/api-message-queue/ue_amq_drain.js, test/@dave/NetSuite/api-message-queue/ss_amq_drain.js, test/@dave/NetSuite/api-message-queue/DEPLOY_RUNBOOK.md, test/@dave/clickup/backfill_opportunity_numbers.php, test/@dave/clickup/probe_opportunity_fields.php, test/@dave/probe_clickup_desc_match.php, test/@dave/test_model_load_behavior.php, dbchanges2/Forecast/2026-06-25a - Add unique index on Opportunities netsuiteOpportunityInternalId.sql, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php |
 | [NetSuite → Forecast Open-Orders Sync (salesOrder webhook → OpenOrderItems)](features/netsuite-salesorder-open-orders-sync.md) | Webhook-driven, single-record port of the legacy open-orders importer (TRUE-79142). | worker2/Worker/Netsuite/SalesOrder.php, worker2/Worker/Netsuite.php, test/@dave/probe_salesorder_rest_shape.php, test/@dave/probe_open_order_lines.php, test/@dave/check_so_status.php, test/@dave/check_so_history.php, test/@dave/probe_so_rest_lines.php, test/@dave/probe_missing_oo_timing.php, test/@dave/probe_missing_oo_createdby.php, test/@dave/probe_drift_so_dates.php, test/@dave/probe_open_order_gating.php, worker/crons/toga2/forecast2/import_open_orders.php, worker/crons/toga2/forecast2/common_import_sales_from_netsuite.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 |

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

@@ -6,17 +6,21 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-10
+updated: 2026-06-29
 owners: [mhammontree]
 files:
   - worker2/Worker/Monitor.php
   - worker2/Worker/Monitors/
+  - worker2/Worker/Monitors/RateEntitlement.php
   - worker2/Worker/Notification/Email.php
+  - worker2/Worker/Rate.php
   - dbchanges2/Core/2026-05-21 - Monitors.sql
+  - dbchanges2/Core/2026-06-29a - Rate Entitlement Contract Monitor.sql
 related:
   - ../architecture.md
   - ./creating-worker-actions.md
   - ../../dbchanges2/architecture.md
+  - ../../../clients/rate/features/aig-contract-creation.md
 ---
 
 ## Summary
@@ -26,10 +30,11 @@ Prudential asset imports, AIG closed claims, …). One orchestrator applies cons
 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).
+**Status (2026-06-29):** v1.0 framework + orchestrator landed; **first child monitor built**
+— `_Worker_Monitors_RateEntitlement` (TRUE-79129, see [worked example](#worked-example--rateentitlement-the-first-child-monitor)).
+`Core.Monitors` migration applied to local Core_2 only — **still not on staging/production
+Core** (coordinate before merge; the new Rate change-set hard-fails where the table is
+absent). 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
@@ -131,6 +136,19 @@ Index `Monitors_isActive_IDX (isActive)`. `Core.CronJobs` reused as-is — one r
   (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.
 
+**Confirmed against the orchestrator (`Worker/Monitor.php`):**
+- The orchestrator calls `$phpClass::Run()` with **no args** and does **not** call
+  `initialize()` on children. A child needing a non-Core connection (e.g. a `Logs_<Client>`
+  DB) must self-register it inside `Run()`, guarding against a double-register:
+  `if (!isset(_Database::$_registers[$alias])) { _Database::register(db, host, user, pass,
+  null, null, $alias); }`, with credentials from `_Config::databaseLogs(...)`. The
+  registration pattern mirrors `worker2/Worker/Rate.php::initialize()`.
+- The orchestrator wraps the call in its own try/catch and turns any `Throwable` into an
+  alert — children must **not** catch (re-confirms the "fail loudly" rule above).
+- A read-only `Run()` (e.g. a log scan) needs **no** `transactionCommit()`.
+- **PHP heredoc gotcha:** `self::CONST` does **not** interpolate inside a heredoc. Bind
+  class constants to local variables before building a heredoc SQL string.
+
 ### Adding a new monitor (runbook)
 
 1. Write the child class (one check, returns `{isOk, message}`).
@@ -150,17 +168,59 @@ No Lambda, SQS, or orchestrator changes needed per monitor.
 - 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.
 
+### Worked example — RateEntitlement (the first child monitor)
+
+`_Worker_Monitors_RateEntitlement` (`worker2/Worker/Monitors/RateEntitlement.php`, the
+**first** file in `Worker/Monitors/`) watches Rate's AIG warranty-contract creation
+(TRUE-79129). It is the reference implementation for the **log-scan** monitor pattern:
+
+1. `Run()` self-registers the `Logs_Rate` connection (the guard + `_Config::databaseLogs`
+   pattern above), because the orchestrator never calls `initialize()`.
+2. Scans `Logs_Rate.Api` for **failed outbound** AIG contract POSTs in the last 30 minutes
+   — `direction = 'OUT'`, `method = 'POST'`, `route LIKE '%/contract'`, and
+   `responseCode` non-2xx **or NULL**. Returns `(object){isOk, message}`; read-only, so no
+   commit.
+3. The detection signal is the `_underscore` **outbound API log**, not the entitlement
+   itself — see [why a monitor is needed](#why-an-external-monitor) below.
+
+The change-set `dbchanges2/Core/2026-06-29a - Rate Entitlement Contract Monitor.sql` does
+the registration: one `Core.Monitors` row (`phpClass = _Worker_Monitors_RateEntitlement`,
+`peopleToNotify = ['devteam@goagilant.com']`, `requiredConsecutiveOks = 2`,
+`reminderFrequencyMinutes = 60`) + one `Core.CronJobs` row (`action = 'Monitor/Run'`,
+`parameters = JSON_OBJECT('monitorId', LAST_INSERT_ID())`, schedule `*/15`,
+`maxExecutionTime = 60`). LAST_INSERT_ID() chains the cron row to the just-inserted monitor.
+
+### Detection via the _underscore outbound API log
+
+`_underscore/ApiRequest.php` logs **every** outbound call to `_Model_Client_Logs_Api`
+(table `Logs_<Client>.Api`) and **commits it immediately**, independent of whether the
+caller later swallows the exception — which is exactly what makes log-scan monitoring
+possible for silent-failure interceptors. Columns to scan: `dtStamp`
+(`FIELD_DATETIME_CREATED`), `direction` (`OUT`), `method`, `hostname` (scheme://host),
+`route` (path after host), `responseCode`. `setUrl()` splits a full URL into
+`hostname` + `route`, so a call to `.../contract` is logged with `route` ending `/contract`
+(and cancellation as `/contract/cancel`). **Pattern for new monitors:** scan the client's
+`Logs_<Client>.Api` rather than trying to detect failure on the business object.
+
+### Why an external monitor
+
+Some interceptors **silently swallow** their own failures (no persistent flag on the
+business record), so the only durable failure signal is the committed outbound API log.
+The Rate case is documented in
+[Rate AIG contract creation](../../../clients/rate/features/aig-contract-creation.md).
+
 ## 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.
+clients' data flows (Compass, Prudential, AIG, Rate, …) 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.
+- **Migration not applied to staging/production Core** — `Core.Monitors`
+  (`2026-05-21 - Monitors.sql`) is on local Core_2 only (as of 2026-06-10, re-confirmed
+  2026-06-29). The new `2026-06-29a` Rate change-set will **hard-fail (table not found)** on
+  any environment where `2026-05-21 - Monitors.sql` has not yet been promoted — confirm the
+  Monitors table exists before deploying.
 - `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
@@ -177,6 +237,7 @@ clients' data flows (Compass, Prudential, AIG, …) but live as separate child c
   HTML email + dashboard deep-links · anti-flap on the alarm side.
 
 ## Change history
+- 2026-06-29 — Built the first child monitor, `_Worker_Monitors_RateEntitlement` (TRUE-79129) + change-set `2026-06-29a`; added the log-scan worked example, the `_underscore` outbound-API-log detection pattern, and confirmed child details (orchestrator never calls `initialize()` so children self-register non-Core connections; no commit on read-only `Run()`; heredoc cannot interpolate `self::CONST`). Re-flagged that `Core.Monitors` is still local-only — the new change-set hard-fails where the table is absent. (mhammontree)
 - 2026-06-10 — Documented the v1.0 monitoring framework (orchestrator, `Core.Monitors` table, recovery-side anti-flap state machine, child contract). First child monitor + staging/prod migration still pending. (mhammontree)
 
 ## Related docs

package/knowledge/INDEX.md

@@ -16,7 +16,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 17 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 18 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 22 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 7 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
@@ -34,6 +34,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## standalone framework
 
 - **togatech** (TOGA Technology Website) — 4 doc(s) → [standalone/apps/togatech/INDEX.md](standalone/apps/togatech/INDEX.md)
+- **websocket** (WebSocket Server) — 2 doc(s) → [standalone/apps/websocket/INDEX.md](standalone/apps/websocket/INDEX.md)
 - **forward** (Forwarder) — 4 doc(s) → [standalone/apps/forward/INDEX.md](standalone/apps/forward/INDEX.md)
 
 ## Clients

package/knowledge/clients/prudential/profile.md

@@ -5,11 +5,12 @@ apps:
   - _underscore
   - api2
   - dbchanges2
+  - websocket
 project: _Underscore
 client: prudential
 type: profile
 status: active
-updated: 2026-06-18
+updated: 2026-06-29
 owners: ["jcardinal", "rgirish"]
 files: []
 related:

package/knowledge/clients/rate/INDEX.md

@@ -2,6 +2,7 @@
 
 | Doc | Framework | Summary | Files |
 |-----|-----------|---------|-------|
+| [Rate AIG Warranty Contract Creation (silent-failure interceptor)](features/aig-contract-creation.md) | 2.0 | When a Rate entitlement is created, `_Model_Rate_Entitlement::postPost` (`_underscore/Model/Rate/Entitlement.php`) creates an **AIG warranty contract** as a non | _underscore/Model/Rate/Entitlement.php, _underscore/ApiRequest.php, worker2/Worker/Monitors/RateEntitlement.php |
 | [Rate Monthly Reconciliation Report](features/monthly-reconciliation-report.md) | 1.0 | A monthly cron that emails an Excel reconciliation report covering all Rate subscription sales orders and their linked PayPal payments for the prior calendar mo | worker/crons/notifications/reports/rate/send_monthly_rate_purchases_report.php, worker/schedules/cron.worker.notification.json |
 | [Rate SalesOrder → NetSuite CashSale Export (postPost)](features/netsuite-cashsale-export.md) | 2.0 | Rate sells home-warranty / home-tech-support products. | _underscore/Model/Rate/SalesOrder.php, _underscore/Model/Rate/Item.php |
 | [Rate SAML SSO](features/saml-sso.md) | 2.0 | Rate uses Azure AD as its IdP (`login.rate.com`). | _underscore/Model/Rate/ClientAuthentication.php, saml/Controller/Index.php, toga2-view/src/hooks/useAuthenticationFlow.ts |

package/knowledge/clients/rate/features/aig-contract-creation.md

@@ -0,0 +1,97 @@
+---
+title: "Rate AIG Warranty Contract Creation (silent-failure interceptor)"
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: rate
+type: client-feature
+status: active
+updated: 2026-06-29
+owners: [mhammontree]
+files:
+  - _underscore/Model/Rate/Entitlement.php
+  - _underscore/ApiRequest.php
+  - worker2/Worker/Monitors/RateEntitlement.php
+related:
+  - clients/rate/profile.md
+  - ../../../2.0/apps/worker2/features/monitoring-framework.md
+---
+
+## Summary
+
+When a Rate entitlement is created, `_Model_Rate_Entitlement::postPost`
+(`_underscore/Model/Rate/Entitlement.php`) creates an **AIG warranty contract** as a
+non-critical side effect: it authenticates against AIG, POSTs to `.../contract`, and on
+success stamps `payload->c_aigContractNumber` and `payload->c_aigContractId` back onto the
+entitlement. **It only attempts this when the entitlement payload has a primary contact
+address.**
+
+The catch: **every failure path is silent.** There is no persistent failure flag on the
+entitlement, so a contract that never got created looks identical to one that did until a
+customer or AIG reports it missing. That is why this flow is watched externally by the
+`_Worker_Monitors_RateEntitlement` monitor rather than by any state on the entitlement.
+
+This is a base-`_underscore` interceptor specific to Rate's product (it lives under
+`Model/Rate/`); documented here as a Rate client-feature because the behavior and its
+monitoring are Rate-scoped.
+
+## How it works
+
+1. `postPost` runs after an entitlement is saved. It proceeds **only if** the payload has a
+   primary contact address; otherwise it does nothing.
+2. Authenticate against AIG (POST `/authentication/login`) → obtain an access token.
+3. POST the contract payload to `.../contract`.
+4. On success: read `aigContractNumber` from the response and set
+   `payload->c_aigContractNumber` + `payload->c_aigContractId`.
+
+## Silent-failure paths (the gotcha)
+
+All of the following fail **silently** — no exception surfaces to the caller and nothing is
+persisted on the entitlement:
+
+- A `try/catch` that only `error_log()`s with the note *"AIG contract creation is
+  non-critical"* and swallows the exception.
+- **Auth response non-2xx** (no throw).
+- **No access token** returned (no throw).
+- **Contract POST non-2xx** (no throw).
+- **Success response but missing `aigContractNumber`** (no throw).
+
+Net effect: there is no durable signal on the entitlement that contract creation failed.
+
+## Detection / monitoring
+
+Because the interceptor swallows failures, detection rides the **committed outbound API
+log** instead. `_underscore/ApiRequest.php` logs every outbound call to
+`_Model_Client_Logs_Api` (table `Logs_Rate.Api`) and commits it immediately, regardless of
+whether the caller later swallows the exception. The AIG contract call lands with
+`direction = OUT`, `method = POST`, and `route LIKE '%/contract'` (cancellation is
+`/contract/cancel`).
+
+`_Worker_Monitors_RateEntitlement` (worker2) scans `Logs_Rate.Api` for failed AIG contract
+POSTs (`route LIKE '%/contract'`, `responseCode` non-2xx **or NULL**) in the last 30
+minutes and alerts the dev team. See the
+[Monitoring Framework worked example](../../../2.0/apps/worker2/features/monitoring-framework.md#worked-example--rateentitlement-the-first-child-monitor).
+
+### Known detection limitation (decided)
+
+Detection matches **only** `POST .../contract` (`route LIKE '%/contract'`), which
+deliberately **excludes** `/contract/cancel` and the shared `/authentication/login`.
+Consequence: a creation failure caused by an **auth failure** is **not** caught, because
+`/authentication/login` is shared with the cancellation flow and so cannot be attributed to
+creation vs. cancellation. This is an accepted, documented limitation — not an oversight.
+
+## Gotchas / known issues
+
+- **No persistent failure flag** — the only durable evidence of a failed contract creation
+  is the outbound API log row, not the entitlement.
+- **Address-gated** — `postPost` does nothing when the payload lacks a primary contact
+  address, so an entitlement with no address never even attempts contract creation (and
+  never logs a `/contract` call).
+- **Auth-induced failures are blind to the monitor** — see the detection limitation above.
+
+## Change history
+
+- 2026-06-29 — Documented the silent-failure AIG warranty-contract interceptor and the
+  external log-scan monitor (`_Worker_Monitors_RateEntitlement`, TRUE-79129), including the
+  accepted detection limitation that auth-induced failures are not attributable (shared
+  `/authentication/login`). (mhammontree)

package/knowledge/clients/rate/profile.md

@@ -6,17 +6,21 @@ apps:
   - saml
   - toga2-view
   - worker
+  - worker2
+  - dbchanges2
 project: SAML SSO Gateway
 client: rate
 type: profile
 status: active
-updated: 2026-06-25
-owners: ["rgirish", "bala"]
+updated: 2026-06-29
+owners: ["rgirish", "bala", "mhammontree"]
 files: []
 related:
   - clients/rate/features/saml-sso.md
   - clients/rate/features/monthly-reconciliation-report.md
   - clients/rate/features/netsuite-cashsale-export.md
+  - clients/rate/features/service-card-entitlements.md
+  - clients/rate/features/aig-contract-creation.md
 ---
 
 ## Summary

package/knowledge/clients/tow-foundation/features/receipt-processing.md

@@ -60,7 +60,7 @@ Credit Card Receipts/
    - **`.docx` files bypass Talos** and route to `extractDocxData()` (Talos returns HTTP 500 on a `.docx` MIME type — it only accepts PDF/image). That method opens the docx as a ZIP, extracts `word/document.xml`, strips tags, and regex-parses `MM/DD/YY: description` lines into `line_items[]`
    - All other types POST to Talos AI `/api/ai/generate` → structured `{vendor_name, invoice_date, total, payment_memo, category, ...}`
    - **Year guard on AI dates** — if Talos returns an `invoice_date` whose year is more than 1 year from the current year (AI hallucination on two-digit year inputs, e.g. `5/13/76` → 1976, `5/28/28` → 2028), the year is clamped to the current year while month/day are preserved
-   - Cross-verify amount ± $0.01 against parsed statement; if matched, override `payment_memo` with the statement description. The statement memo is the **authoritative source for activity-purpose headings** (Grantee meeting, Peer meeting, Grantee event, etc.); the AI memo is good for location/detail but defaults to a bare `"Transportation:"` heading on ride-share/taxi receipts even when the receipt has handwritten activity notes. The override now fires when **either** the AI `payment_memo` is empty **or** it is a bare transportation memo — `isBareTranportationMemo()` returns true when the memo (left-trimmed) starts with `"Transportation:"`. Previously the override only fired on an empty AI memo, so a wrong `"Transportation:"` heading was never corrected.
+   - Cross-verify amount ± $0.01 against parsed statement; if matched, the statement description **may** override `payment_memo`. The statement memo is the **authoritative source for activity-purpose headings** (Grantee meeting, Peer meeting, Grantee event, etc.) — but only when it actually *is* such a heading. The Amex statement's `Description` column for ride-share/taxi charges holds raw bank strings (e.g. `"AplPay LYFT 855-280-0278 CA"`, `"UBER"`), not activity headings. **Priority order (enforced):** (1) statement memo wins only if it is a proper activity heading; (2) otherwise the AI memo is kept — including when the statement only has a raw bank string, because the AI's descriptive memo (e.g. `"Transportation: Lyft ride from East Side at 105th to 925 9th Ave"`) is more useful than a raw Apple Pay string. The override condition is `empty($extracted->payment_memo) || self::isActivityHeadingMemo($matched)`. `isActivityHeadingMemo()` returns true only when the statement memo (left-trimmed, lowercased) starts with a recognised activity-purpose prefix followed by a colon (`grantee meeting:`, `grantee event:`, `peer meeting:`, `colleague meeting:`, `staff theater:`, `professional development:`, `dining:`, `travel:`). This **replaces** the earlier `isBareTranportationMemo()` approach, which fired whenever the AI memo started with `"Transportation:"` and so let the raw bank string overwrite a useful AI memo on ride-share rows (degraded rows 1, 17, 18, 21, 26, 31, 32, 34 on Emily Tow's statement).
    - **Zero-total fallback** — if the extracted/docx total is 0, `lookupStatementTotalByVendor()` derives the amount from the billing statement (see *Statement structure* below)
    - Build base filename (no suffix yet) and store in `$pendingRenames`
    - On extract failure → move to `Archive/exception/` immediately
@@ -236,6 +236,7 @@ Fatal errors send only to `NOTIFY_EMAIL_DEV` (no CC/BCC).
 
 ## Change history
 
+- 2026-06-29 — **Reversed the over-aggressive memo override.** Replaced `isBareTranportationMemo()` (added earlier same day) with `isActivityHeadingMemo()`: the statement memo now overrides the AI memo **only** when it is a proper activity-purpose heading (e.g. `Grantee meeting:`, `Peer meeting:`), not whenever the AI memo started with `"Transportation:"`. The previous approach replaced semi-useful AI memos with raw bank strings (`"AplPay LYFT …"`, `"UBER"`) on ride-share/taxi rows where the statement has no activity heading — degraded 8 rows on Emily Tow's statement (1, 17, 18, 21, 26, 31, 32, 34). New priority: statement heading > AI memo, with AI memo kept for any non-heading statement description. (rgirish)
 - 2026-06-29 — `payment_memo` override now also fires on a **bare** `"Transportation:"` AI memo, not just an empty one: new `isBareTranportationMemo()` lets the cardholder's statement Excel (the authoritative source for activity-purpose headings like "Peer meeting:", "Grantee event:") override the AI's generic transportation heading. Fixes wrong headings on Emily Tow May 2026 transit rows. Added the committed `MoveBack` action (+ `collectFilesRecursiveRaw()`) to restore a person's archived receipts into a billing-cycle folder for reprocessing, replacing the throwaway `/tmp/tow_restore_archives.php` script. (rgirish)
 - 2026-06-25 — Statement parsing hardened for Emily Tow's May 2026 Amex xlsx: `loadStatementExcel()` now iterates `getAllSheets()` (4 weekly-period sheets) instead of `getActiveSheet()` and captures the `Receipt` column; `lookupStatementTotalByVendor()` now **sums** all receipt-label-matched rows (14 × $3.00 "Subway Rides" = $42.00) before falling back to description-keyword match — fixes subway totals reading $0/$9.00. Added `extractDocxData()` so `.docx` receipts bypass Talos (Talos 500s on docx), parsing `MM/DD/YY: description` line items into per-entry Excel rows. Added a year guard clamping AI-hallucinated `invoice_date` years (e.g. 1976, 2028) to the current year. Fixed archive-path bug: SharePoint move now uses the actual folder name (`"Emily Tow CC receipts"`) not the normalized name, fixing 404 on archive moves. 5 more vendors found missing from the QB vendor list (client action). (rgirish)
 - 2026-06-23 — `TowFoundationCategories.php` added: AI category values now mapped to exact QB account strings via `mapCategory()`; `"Transportation"` → `"6610 Travel expense"` etc. (19 mappings). QB vendor substring match minimum lowered from 4 to 3 chars with whole-word boundary guard for short needles — fixes `"CVS"` → `"CVS Pharmacy"`, `"MTA"` → `"MTA Metro card"`, prevents `"UPS"` → `"USPS"` false positive. (rgirish)

package/knowledge/registry.json

@@ -96,6 +96,16 @@
     "role": "app",
     "dependsOn": []
   },
+  {
+    "repo": "websocket",
+    "project": "WebSocket Server",
+    "framework": "standalone",
+    "role": "app",
+    "dependsOn": [
+      "api2",
+      "_underscore"
+    ]
+  },
   {
     "repo": "webhook",
     "project": "Webhook",

package/knowledge/standalone/apps/websocket/INDEX.md

@@ -0,0 +1,6 @@
+# websocket (WebSocket Server) — standalone knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [WebSocket Server Architecture](architecture.md) | `websocket` (npm package `toga-socket-server`) is the real-time push tier for TOGA 2.0 frontends. | websocket/index.js, websocket/auth.js, websocket/rooms.js, websocket/fanout.js, websocket/metadata.js, websocket/ecosystem.config.js, websocket/aws-setup.sh, websocket/package.json |
+| [SQS Fan-out to Socket.io Rooms](features/sqs-fanout.md) | The fan-out logic that turns one SQS `toga-events` message (published by api2 after a write) into `record:changed` emits to every Socket.io room that should lea | websocket/fanout.js, websocket/metadata.js, websocket/rooms.js |

package/knowledge/standalone/apps/websocket/architecture.md

@@ -0,0 +1,90 @@
+---
+title: WebSocket Server Architecture
+framework: "standalone"
+repo: websocket
+project: WebSocket Server
+client: shared
+type: architecture
+status: active
+updated: 2026-06-29
+owners: [rgirish]
+files:
+  - websocket/index.js
+  - websocket/auth.js
+  - websocket/rooms.js
+  - websocket/fanout.js
+  - websocket/metadata.js
+  - websocket/ecosystem.config.js
+  - websocket/aws-setup.sh
+  - websocket/package.json
+related:
+  - ../../../2.0/apps/_underscore/features/event-publish-sqs.md
+---
+
+## Summary
+
+`websocket` (npm package `toga-socket-server`) is the real-time push tier for TOGA 2.0
+frontends. It is a **standalone Node.js / Socket.io server** — it uses neither PHP
+framework (`_underscore` 2.0 nor `App_` 1.0), which is why it lives under the
+`standalone/` knowledge partition. It consumes the `toga-events` SQS queue published by
+`api2` (via `_Event::publish()` in `_underscore`) and fans out `record:changed` events to
+connected browsers over Socket.io rooms. It ships no client-facing CRUD of its own.
+
+**Critical rules:**
+- It is a **consumer** of an event contract owned by the PHP side — the event payload
+  shape is defined by `_underscore`'s `_Event::publish()`. Changes to the payload must be
+  coordinated across both repos (see the related `event-publish-sqs` feature doc).
+- Room keys use **`clientUuid`**, not `clientId` — the per-tenant isolation boundary.
+- All secrets (`TOGA_JWT_SECRET`/`API_SECRET_ACCESS_TOKEN`, `SQS_*`, `DB_*`) come from env
+  (`.env` locally, Elastic Beanstalk env vars in prod) or the Core DB. Never commit values.
+- JWT secrets are **sourced at runtime from `Core.Parameters`** (`API_SECRET_ACCESS_TOKEN`
+  + `_PREVIOUS`) so the server stays in sync as api2 rotates them every 3–10 days.
+
+## Stack
+
+- **Node.js ≥ 18**, **Socket.io 4.7**, **@aws-sdk/client-sqs 3**, **mysql2 3**,
+  **jsonwebtoken 9** (HS256), **dotenv**.
+- Process management via **PM2** (`ecosystem.config.js`, 2 workers, auto-restart).
+- Deployed to **AWS Elastic Beanstalk**; `aws-setup.sh` provisions an instance and is
+  reusable across multiple environments.
+
+## Pipeline
+
+```
+api2 PHP write (POST/PUT/PATCH)
+  → _underscore _Event::publish() → SQS toga-events queue
+    → this server polls SQS (long-poll loop)
+      → fanOut() → Socket.io rooms → connected browsers (record:changed)
+```
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `index.js` | HTTP server, Socket.io init, SQS poll loop startup |
+| `auth.js` | JWT validation middleware (HS256, same secret as api2) |
+| `rooms.js` | `subscribe` / `unsubscribe` handlers; `listRoom()` / `instanceRoom()` helpers |
+| `fanout.js` | SQS message → room emit (fan-out to list + instance + parent + child rooms) |
+| `metadata.js` | Core DB cache (route→id, parent/children maps, JWT secrets); refreshed every 5 min |
+| `ecosystem.config.js` | PM2 config |
+| `aws-setup.sh` | Elastic Beanstalk provisioning |
+
+## Room naming
+
+```
+List room:      toga:{clientUuid}:record:{recordRoute}
+Instance room:  toga:{clientUuid}:record:{recordRoute}:{uuid}
+```
+
+## Metadata cache (`metadata.js`)
+
+A single Core DB connection-per-refresh (every 5 minutes, plus at startup) populates three
+in-memory maps plus the JWT secret list:
+
+- `routeMap` — `route` string → `recordId` (from `Core.Records`).
+- `parentMap` — child `recordId` → parent `recordId` (from `Core.InherentRecordChildren`,
+  column `inherentChildOfRecordId`).
+- `childrenMap` — parent `recordId` → `Set` of child `recordId`s (inverse of `parentMap`).
+- `jwtSecrets` — `[current, previous]` from `Core.Parameters`, checked in order on verify.
+
+Accessors: `getRouteMap()`, `getParentMap()`, `getChildrenMap()`, `getJwtSecrets()`.

package/knowledge/standalone/apps/websocket/features/sqs-fanout.md

@@ -0,0 +1,86 @@
+---
+title: SQS Fan-out to Socket.io Rooms
+framework: "standalone"
+repo: websocket
+project: WebSocket Server
+client: shared
+type: feature
+status: active
+updated: 2026-06-29
+owners: [rgirish]
+files:
+  - websocket/fanout.js
+  - websocket/metadata.js
+  - websocket/rooms.js
+related:
+  - ../../../../2.0/apps/_underscore/features/event-publish-sqs.md
+---
+
+## What it is
+
+The fan-out logic that turns one SQS `toga-events` message (published by api2 after a
+write) into `record:changed` emits to every Socket.io room that should learn about the
+change. Implemented in `fanOut(event)` in `websocket/fanout.js`, driven by a continuous
+SQS long-poll loop.
+
+## How it works
+
+`pollLoop()` long-polls SQS (`MaxNumberOfMessages: 10`, `WaitTimeSeconds: 20`), parses each
+message body to an `event`, calls `fanOut(event)`, then deletes the message. Malformed
+bodies are logged and deleted (not retried); fan-out errors are logged without deleting
+fan-out from blocking the loop. On a receive error it backs off 5s before retrying.
+
+`fanOut(event)` reads `{ clientUuid, recordRoute, uuid, httpMethod, dtEvent, parentRoute,
+parentUuid }` and emits to up to four kinds of rooms (all keyed by `clientUuid`):
+
+1. **Own list room** — `listRoom(clientUuid, recordRoute)` — always.
+2. **Own instance room** — `instanceRoom(clientUuid, recordRoute, uuid)` — only when `uuid`
+   is present.
+3. **Inherent children's list rooms** — for each child of the fired record, emit to that
+   child's list room with `{ ...payload, parentRoute: recordRoute }`. Resolved from the
+   metadata `childrenMap` (parent recordId → Set of child recordIds), looked up via
+   `routeMap` to translate the fired `recordRoute` → `recordId` → child recordIds → child
+   routes. This lets a list view of children refresh when the parent changes (e.g. a
+   `service-requests` write notifies `service-request-bundles`, `service-request-units`,
+   and `service-request-notes` list rooms).
+4. **Parent rooms** — when the event itself is a nested write, notify the parent's list
+   room (always) and instance room (only if `parentUuid` present) with
+   `{ ...payload, childRoute: recordRoute }`.
+
+### Parent-route resolution from metadata
+
+When api2 posts a flat URL with no `parentRoute` in the event, `fanOut()` resolves the
+parent itself: it reuses the `recordId` already looked up for step 3, then reads
+`getParentMap().get(recordId)` (child recordId → parent recordId) and reverse-looks-up the
+parent's route from `routeMap`. So parent notifications work even when the publisher did
+not supply `parentRoute`.
+
+## Frontend subscription
+
+The frontend joins rooms by emitting `subscribe` once per route — there is **no server-side
+array support and none is needed**. Multiple sequential emits each join a distinct
+Socket.io room and are effectively simultaneous from the client's perspective:
+
+```js
+const routes = ['service-requests', 'service-request-bundles', 'service-request-units'];
+routes.forEach(route => socket.emit('subscribe', { record: route }));
+socket.on('record:changed', (payload) => { /* refresh the matching list/detail view */ });
+```
+
+## Gotchas
+
+- Room keys are built from **`clientUuid`**, never `clientId` — using `clientId` cross-wires
+  tenants or misses rooms entirely.
+- The children-room lookup is a nested scan of `routeMap` (recordId → route) per child; it
+  is correct but O(routes × children) — fine at current route counts, watch if routes grow.
+- Children notification depends on `Core.InherentRecordChildren` being populated and the
+  metadata cache being fresh (refreshes every 5 min) — a brand-new parent/child relation
+  will not fan out until the next refresh.
+
+## Change history
+- 2026-06-29 — Added inherent-children list-room notification: a parent write now emits
+  `record:changed` (with `parentRoute`) to each inherent child's list room, via new
+  `childrenMap` / `getChildrenMap()` in metadata.js. Parent-route resolution reuses the
+  recordId/routeMap lookup from the children step. (rgirish)
+- 2026-06-26 — Initial fan-out loop: SQS long-poll → list + instance + parent rooms, with
+  malformed-message drop and fan-out error isolation. (rgirish)

package/package.json

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