toga-ai 1.0.231 → 1.0.233

package/knowledge/1.0/apps/worker/features/forecast2-netsuite-reconciliation.md

@@ -405,11 +405,27 @@ None — Forecast2 is a single shared dataset.
   longer open — so it **removes** billed/closed orders rather than resurrecting them. It is therefore
   **not** a resurrection risk against the webhook `removeAll` path; it is in fact the current backstop
   deleter for orders the webhook never sees billed (the invoice-transform gap).
+- **`fixer.php`'s OpenOrderItems path does NOT carry `locationId` / `quantityBackordered` /
+  `amountDue` — mirror any new open-order column here or the reconciler reverts it.** `fixer.php`
+  already handles anchor-line **`amountDue` on the Sales path**, guarded by a column-existence check
+  `$hasAmountDueCol = forecastColumnExists('Sales','amountDue')` (so it's a no-op until the prod
+  column lands). Its **OOI** path — the lookup SELECT, change-detection, the
+  `buildOoiInsertSql`/`buildOoiUpdateSql` helpers, and the SuiteQL `transactionline` query — does
+  **not** include `locationId`/`quantityBackordered`/`amountDue`. Per the compute-identically
+  invariant, any field added to the open-order **importer** (TRUE-79162) must also be added to this
+  OOI path (and ideally behind the same `forecastColumnExists` guard pattern) or `fixer.php`/`looper`
+  will overwrite the importer's value to NULL on its next run.
 - These tools live in `test/@dave/` (developer tooling), but `trueup_open_orders` has been run
   against production. The `Defaults`/checkpoint mechanics of the scheduled sync are separate.
 
 ## Change history
 
+- 2026-06-29 — **Recorded that `fixer.php`'s OOI path lacks `locationId`/`quantityBackordered`/
+  `amountDue`** (planning for TRUE-79162). The Sales path already handles anchor-line `amountDue`
+  behind a `forecastColumnExists('Sales','amountDue')` guard; the OpenOrderItems path (lookup SELECT,
+  change-detection, `buildOoiInsertSql`/`buildOoiUpdateSql`, SuiteQL `transactionline`) carries none
+  of the three new open-order fields. Per the compute-identically invariant, any field added to the
+  open-order importer must be mirrored here or the reconciler reverts it. (dfranks)
 - 2026-06-29 — **Found/fixed the NULL-rate phantom open-order profit drift; extended PROFIT comparison to all
   three categories.** Cost-only NS open-order lines (zero revenue) can have a **NULL `rate`**; the FIND
   profit SQL did `tl.rate - unitCost` and `NULL - x = NULL` silently dropped the line from `SUM`, inflating

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/2.0/apps/worker2/features/netsuite-salesorder-open-orders-sync.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-06-25
+updated: 2026-06-29
 owners: ["dfranks"]
 files:
   - worker2/Worker/Netsuite/SalesOrder.php
@@ -127,12 +127,51 @@ The table lives in the **`Forecast` schema on the core2 cluster** (reader
 sales-order FK column is **`netsuiteSalesOrderInternalId`** (`int unsigned`) — note this is *not* the
 same column name used by `Forecast.Sales` (see the column-name gotcha below).
 
+### Model/DB drift to know before backfilling location / backorder / amountDue (TRUE-79162)
+
+A planned backfill of **location, backorder, and amount-due** data onto open orders runs into three
+schema/model facts (all verified against the prod core2 reader; nothing built yet):
+
+- **`_Model_Forecast_OpenOrderItem` (`_underscore/Model/Forecast/OpenOrderItem.php`) does NOT declare
+  `locationId` or `quantityBackordered` — even though both columns already exist in the prod
+  `Forecast.OpenOrderItems` table** (`locationId` `int unsigned NULL`, `quantityBackordered`
+  `decimal(15,4) NULL`). The model declares only `id, netsuiteSalesOrderInternalId, dateOrder,
+  orderNumber, customerId, salesRepEmployeeId, classificationId, accountId, itemId, lineNumber,
+  revenue, profit`. **Writing those two fields through the 2.0 importer requires adding the
+  properties to the model first** — the column existing in the DB is not sufficient.
+- **`Forecast.Locations` is EMPTY in prod (0 rows).** Schema: `id, name, netsuiteInternalLocationId`
+  (UNIQUE, nullable), `typeId` — **no parent/hierarchy column.** Any open-order `locationId`
+  resolution returns NULL until this table is populated from NetSuite, so **populating `Locations` is
+  a hard prerequisite** for the location backfill. NetSuite returns a **leaf sub-location** but the
+  warehouse dashboard wants the **top-level location**, so a leaf→root rollup is needed (and there is
+  no parent column on `Locations` today to express it).
+- **`Forecast.OpenOrderItems` has NO `amountDue` column** (neither does `Forecast.Sales` in prod —
+  see the [Sales import doc](../../_underscore/features/forecast-sale-import.md)), and `amountDue`
+  appears in no worker2 Netsuite handler or `_Model_Forecast_*`. Importing open-order amountDue
+  needs a **new column + model field**. The amountDue source semantics from the prior Sales work
+  (TRUE-78923) — REST `amountRemaining` / SuiteQL `foreignamountunpaid`, **anchor-line only, store
+  RAW POSITIVE** — carry over, **but `amountRemaining` is an AR/invoice field**, so for an *unbilled*
+  sales order it may return null/0. **Live-probe an open SO before finalizing** the open-order
+  amountDue source.
+
 ## Client variations
 
 None — uniform (platform-wide Forecast2 sync).
 
 ## Gotchas / known issues
 
+- **A new synced `OpenOrderItems` column must be wired into BOTH `buildOpenLineRows()` AND the
+  `syncOpenLines()` change-detection diff — not just the write — or no-diff updates silently drop
+  it.** The forward-sync path is `_Worker_Netsuite_SalesOrder`'s private `buildOpenLineRows()`
+  (assembles each `OpenOrderItems` row array) and `syncOpenLines()` (change-detection + upsert).
+  This is the established forecast2 change-detection gotcha applied to open orders: a column added
+  only to the row build but not to the `syncOpenLines()` diff block is **discarded on a no-change
+  UPDATE** (the diff sees no difference, so the new value never persists). Any
+  locationId/quantityBackordered/amountDue addition (TRUE-79162) must touch both. Forward sync now
+  flows through this webhook importer; the legacy 1.0 cron
+  (`worker/crons/toga2/forecast2/common_import_sales_from_netsuite.php` open-order section) is
+  superseded for it. **Also mirror any new field into the reconciler `test/@dave/fixer.php` OOI path**
+  or it reverts the value on its next run (see the reconciliation doc).
 - **Billing an SO via invoice-transform flips it to "Billed" WITHOUT firing the SalesOrder afterSubmit UE → no edit/PUT webhook → `removeAll()` never runs → the OpenOrderItems rows linger (this is the real cause of the "billed order not removed" problem — NOT a removeAll-didn't-persist bug).** When a NetSuite Sales Order is billed by **creating an Invoice from it**, the SO's `status` transitions to `Billed` as a **side-effect of the invoice transform** — this does **not** trigger the SalesOrder `afterSubmit` User Event, so the AMQ enqueuer (`ue_api_msg_queue_enqueue`, deployed per-record-type) **never emits an edit/PUT webhook for the SO**. Consequently `_Worker_Netsuite_SalesOrder` is never invoked for the billing change, `importOpenOrder`'s status gate (which *would* call `removeAll` on a non-open status) never runs, and the order's `OpenOrderItems` rows survive until the nightly discrepancy-fix cron deletes them. **Confirmed live 2026-06-24/25 on SO 7190415** (tranId 280387): only a `create` webhook delivery exists in `Logs.Webhook` (2026-06-24 23:48, 16 rows inserted) — **NO** edit/delete delivery at billing time (~09:41 UTC 2026-06-25); `Core.WorkerJobs` shows only `Netsuite/Webhook` + `Netsuite/SalesOrder/post` (no put/delete); `Logs.Api` has only the original NS GET + a 200 `OPEN_ORDER_IMPORT` breadcrumb — **no 204 removeAll breadcrumb**. The invoice (7190621) that billed it **also produced no webhook** — its 16 `Forecast.Sales` rows came from the **legacy 5-min pull cron**, not the webhook. **This corrects the earlier suspicion that "removeAll fired but DB didn't persist"** — both `removeAll` paths *do* commit `DB_FORECAST`; `removeAll` was simply **never called**. **Diagnostic ladder for a lingering billed order:** `Logs.Webhook` (was an edit/delete even delivered? — here, no) → `Core.WorkerJobs` (was a put/delete processed? — no) → `Logs.Api` `source='OPEN_ORDER_IMPORT'` (any 204 removeAll breadcrumb? — no). **Fix direction (not yet implemented):** the SalesOrder-side enqueuer must also fire on the invoice-transform status change — either deploy the AMQ enqueuer on **Invoice** so the bill event drives an SO re-sync, or have the SalesOrder handler re-evaluate the SO when its child invoice arrives; until then the **stopgap is the continuous `loop_trueup_open_orders.php --by-lastmodified` runner** (see the reconciliation doc), which windows on `lastmodifieddate` so it catches an order billed today whose `tranDate` predates the window. The `removeAll` path in `SalesOrder.php` was re-confirmed correct in this session.
 - **Wrong FK column name → MySQL 1054 that masquerades as "order missing".** `OpenOrderItems`'s
   sales-order key is **`netsuiteSalesOrderInternalId`**. Do **NOT** query it with
@@ -297,6 +336,16 @@ test fixture (it surfaced the stale SO 7181316 above).
 
 ## Change history
 
+- 2026-06-29 — **Recorded the model/DB drift + prerequisites for the open-order location/backorder/
+  amountDue backfill (TRUE-79162, planning only — no code written).** `_Model_Forecast_OpenOrderItem`
+  declares neither `locationId` nor `quantityBackordered` though both columns already exist in prod
+  `OpenOrderItems` (so the model needs the properties before the importer can write them);
+  `Forecast.Locations` is empty in prod with no parent column (hard prerequisite + leaf→root rollup
+  needed); `OpenOrderItems` has no `amountDue` column (new column + field required, and
+  `amountRemaining` is an AR field that may be null/0 on an unbilled SO — probe first). Added the
+  gotcha that any new synced column must be wired into **both** `buildOpenLineRows()` and the
+  `syncOpenLines()` change-detection diff (and mirrored in `fixer.php`'s OOI path) or it is dropped on
+  no-diff updates. (dfranks)
 - 2026-06-25 — **Root-caused "billed SO not removed from OpenOrderItems in real time" to a missing
   webhook, NOT a removeAll-didn't-persist bug.** Billing an SO via invoice-transform flips it to
   `Billed` as a side-effect that does **not** fire the SalesOrder `afterSubmit` UE → the AMQ enqueuer

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)

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/package.json

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